Page Comparison

You can read more about the merge model, as well as two alternate ways of getting your changes reflected - "includes" files and "overlay" files - in Merging your changes into CollectionSpace's Application layer.

If you wish to temporarily override host-specific settings for your tenant, without altering your more permanent settings, you can add those temporary settings to a local-{mymuseum}-settings.xml file, that resides alongside the settings.xml file within your tenant folder. (The {mymuseum} part of this file's name will be the actual short name of your museum; for instance, if your museum's short name was walkerart, this file would be named local-walkerart-settings.xml.)

You can find an example that temporarily overrides a single cache-related setting in the sample Lifesci tenant.

{multi-excerpt:name=identify-relevant-default-config-file}
* Identify the relevant default configuration file with the settings for a particular type of record or some other discrete aspect of CollectionSpace's configuration that you want to change. This will be a file whose name starts with {{base-}}, residing in the {{defaults}} folder.

{tip}
There are a large number of *default configuration files* residing in a {{defaults}} folder, whose names all begin with {{base-}}. These files contain default settings that affect the behavior of a CollectionSpace system, including record- and field-level settings, vocabulary settings and more.

The following are several representative examples:
* {{base\-collectionobject.xml}}, configures the default Cataloging (aka CollectionObject) record and its fields.
* {{base\-procedure\-acquisition.xml}}, configures the default Acquisition record and its fields.
* {{base\-authority\-person.xml}}, configures the default Person record and most of its fields - except for the fields in its repeatable term information group, which are configured in a separate file, {{base\-authority\-person\-termList.xml}}.
* {{base\-instance\-vocabularies.xml}}, configures some default term lists (aka controlled lists of vocabulary terms).

For a full list of these default configuration files and their purposes, see [Default configuration files in the Application layer].
{tip}
{multi-excerpt}

{multi-excerpt:name=create-delta-config-file}
* Find the relevant configuration file within your tenant folder, corresponding to a particular type of record or some other discrete aspect of CollectionSpace's configuration that you want to change.
* Or, if that file doesn't already exist, create a new, empty text file within your tenant folder, corresponding to the default configuration file for the record or other aspect of configuration you want to change. (See below for conventions when naming that file.)
** This file will contain just the settings you want to add or change; its contents will be merged into the default configuration file. (You might think of this file as containing just the "deltas" from the default settings.)
** By convention, if you wanted to selectively change or supplement the settings in a default configuration file named, for instance, {{base\-procedure\-acquisition.xml}}, the configuration file in your tenant folder in which you will do this might be named something like {{\{mymuseum\}\-procedure\-acquisition.xml}}, where {{\{mymuseum\}}} represents the actual short name of your museum. For instance, if your museum's short name was {{walkerart}}, this file might be named {{walkerart\-procedure\-acquisition.xml}}.
** You can create or edit this file using your favorite text or XML editor.
{multi-excerpt}

{multi-excerpt:name=edit-master-config-with-merge-instructions}
* Find the main ("master") configuration file for your tenant - the file that ties together all of your individual configuration files.
** This main ("master") configuration file is named {{\{mymuseum\}-tenant.xml}}, where {{\{mymuseum\}}} represents the actual short name of your museum. (For instance, if the short name of your museum were {{walkerart}}, that file would be named {{walkerart-tenant.xml}}.) It can be found two levels above your tenant folder, in the folder that contains both the {{defaults}} and {{tenant}} folders. See [Finding your tenant folder] for a diagram that may help you find this file.
* In that {{\{mymuseum\}-tenant.xml}} configuration file, find the XML element, or "tag," that mentions the default configuration file whose settings you want to change. (For a list of these default configuration files and their purposes, see [Default configuration files in the Application layer].) For example, that tag might initially look something like this, which brings in the default settings for the Acquisition record and its fields:
{code}
<include src="base-procedure-acquisition.xml"/>
{code}
* If that tag hasn't already been modified to specify that the configuration file you have created within your tenant folder should be merged into its corresponding default configuration file, do so now; edit that tag with these two additions:
** The name of your museum's configuration file, the file which contains just your changes to the default configuration.
** The name of a merge properties file that will specify how your changes are to be merged into the defaults.  (In most cases, the default merge properties file, {{xmlmerge.properties}}, contains sensible merge rules that will do exactly what you need. You can [view that default merge properties file|https://github.com/collectionspace/application/blob/master/tomcat-main/src/main/resources/defaults/xmlmerge.properties] for commented descriptions of those merge rules. In the rare instances where you might need to do this, you could also create and reference your own merge properties file.)
* After modification, that tag might now look something like this:
{code}
<include src="base-procedure-acquisition.xml,{mymuseum}-procedure-acquisition.xml" merge="xmlmerge.properties" />
{code}
where {{\{mymuseum\}}} is the actual short name for your museum. This specifies that the contents of your tenant's {{\{mymuseum\}\-procedure\-acquisition.xml}} file will be merged into the default configuration file, {{base\-procedure\-acquisition.xml}}, via the merge rules specified in the file {{xmlmerge.properties}}.
\\
\\
For instance, if your museum's short name was {{walkerart}}, that tag might now look something like this:
{code}
<include src="base-procedure-acquisition.xml,walkerart-procedure-acquisition.xml" merge="xmlmerge.properties" />
{code}
{multi-excerpt}

For detailed examples on how to edit the Application layer configuration files in your tenant folder, see Merging your changes into CollectionSpace's Application layer.

{multi-excerpt:name=deploying-changes-application}
To make your changes "live," you'll need to copy (deploy) them to the CollectionSpace server:

* At your operating system's shell or command prompt, within the {{application}} folder in which you checked out the Application layer source code (e.g. several levels up from your tenant folder), enter:
{code}
mvn clean install -DskipTests
{code}

This will copy (deploy) your tenant folder, containing all of your modified files, to the appropriate place(s) within the CollectionSpace server folder. (Your tenant folder will be packaged up inside the Application layer's {{collectionspace.war}} file, and that file, in turn, will be copied into the {{webapps}} directory of the server folder.)
{multi-excerpt}

{multi-excerpt:name=deploying-changes-services}
After making changes in the Application layer, you will usually need to automatically generate equivalent files in CollectionSpace's Services layer, and get those files copied to the CollectionSpace server folder, as well.  Here's how to do this:

* [Shut down the CollectionSpace servers|Shutting Down the CollectionSpace Server]
* Wait at least 30 seconds to ensure that the servers have fully shut down.
* At your operating system's shell or command prompt, within the {{services}} folder in which you checked out the Services layer source code:
* Change into the {{services/JaxRsServiceProvider}} folder.
* Enter the following command at your operating system's command prompt:
{code}
ant deploy_services_artifacts
{code}
This will automatically generate a variety of files needed by CollectionSpace's Services layer, matching the changes you've made in the Application layer, and copy them into the right places within the CollectionSpace server folder.
* [Start up the CollectionSpace servers|Starting Up the CollectionSpace Server].
{multi-excerpt}

This is pretty esoteric, but when you make certain changes, you can avoid having to automatically generate equivalent files in the Services layer. By not having to generate these files, you can potentially save up to 1-2 minutes for each change you make.

When making changes to Application layer files, you'll also need to automatically generate equivalent files in the Services layer in the vast majority of cases:

IF

• The default configuration file whose settings you wish to change or supplement contains a generate-services-schema="true" attribute value; e.g.:

  Code Block
  <record id="acquisition" in-findedit="yes" type="record,procedure" cms-type="default" generate-services-schema="true">

AND

• If your changes affect global behavior of a record in any way
  OR
• If you have:
  • Fundamentally changed the behavior of any field; for instance, by changing its data type, or altering whether it should appear in search and list results.
  • Added a field.
  • Removed a field.

If you've made only very minor changes that don't fundamentally change the behavior of a record or field, you might not always need to generate equivalent files in the Services layer. One example of such a minor change is if you modify the choices of data options that a user can make within a field, such as the set of options they can choose from a dropdown menu, or the set of vocabularies associated with an autocomplete field, that provide term matching suggestions as a user types into that field.

As a bottom line: if you don't know for certain whether you need to generate these Services layer files, it can't hurt to do it anyway.

In some cases, you may need to clear both your browser's standard cache and its "offline" or HTML 5 "application" cache, to be able to see the effects of your changes.

In some cases, you may need to clear both your browser's standard cache and its "offline" or HTML 5 "application" cache, to be able to see the effects of your changes.

{multi-excerpt-include:pageTitle=Merging your changes into CollectionSpace's Application layer|name=testing-merges-via-merge-files|nopanel=true}