Merging your changes into CollectionSpace's Application layer

Configuring CollectionSpace's Application Layer - An Overview provides an overview of the process by which you can change settings in CollectionSpace's Application layer, the key way that you can configure CollectionSpace's behavior to meet the needs of your museum.

It describes the mechanics of how you can do so, by creating configuration files whose settings will be merged into CollectionSpace's default configuration files, and then telling the Application layer about the existence of your museum's configuration files, so they'll automatically be merged into the default settings.

This document continues where that one leaves off. It gives an overview of what content should go into your museum's configuration files, so that they can change or add to the default settings.

In the configuration files you create within the tenant folder for your museum, in CollectionSpace's Application layer source code tree, you can change CollectionSpace's default behaviors for records, fields, search and list results, and more. You can change some of the default settings, add to the default settings (such as adding new fields), or do both of these things.

Just a few examples of the many kinds of changes you can make:

• Add new fields to records (via community of practice or museum-specific extension schemas).

• Specify which authorities - and vocabularies within those authorities - are associated with autocomplete fields (via "instances" blocks in Application layer configuration).

• Change the items in certain dropdown menus (via "enums" blocks in Application layer configuration).

• Change the fields returned in search and list results (via "mini=" attributes on individual fields).

• Identify which selectors in HTML templates will be targeted by data sent by the Application layer to the UI layer.

In most instances, you'll want the settings in the configuration folders in your tenant folder to be merged into the default settings. This gives you the most fine-grained control. However, you can also specify that your settings are to be included into the defaults, or overlay (replace outright) the defaults.

By following the instructions in Configuring CollectionSpace's Application Layer - An Overview, the settings in configuration files in the tenant folder for your museum will be merged into their corresponding default configuration files via sensible rules specified in the xmlmerge.properties file.

You can view these rules by viewing the copy of the xmlmerge.properties file in the Application layer source code. Each rule is clearly commented.

The easiest way to learn how to merge in your own museum's settings, to supplement or replace default settings, is to look at available examples. Here are a few common scenarios:

In the sample Lifesci tenant included in the standard CollectionSpace system distributions, a set of additional fields - all contained within a naturalhistory extension schema - are added to the standard Cataloging record. This includes taxonomic identification / determination history fields, as well as other fields that supplement the standard Cataloging record.

The main ("master") configuration file for the Lifesci tenant, lifesci-tenant.xml file contains an XML element ("tag") that specifies that a natural history-specific configuration file, naturalhistory-collectionobject.xml, is to be merged into the default configuration file for the Cataloging record, base-collectionobject.xml.

And that natural history-specific configuration file, naturalhistory-collectionobject.xml, is itself fairly straightforward. This file:

• Matches on the top tag (<record id= ...>) in the default configuration file.

• Adds a <services-record-path> tag inside it, identifying the naturalhistory extension schema.

• Matches on a <section id="identificationInformation"> tag, which encloses the fields that are included in the topmost Identification Information section of the Cataloging record.

• Provides tags for each of the extension schema's fields that will supplement the standard fields in this section of the Cataloging record.

In the sample Lifesci tenant included in the standard CollectionSpace system distributions, the configuration for various vocabularies has been modified from the default settings: to change the default behavior related to a user's ability to select non-preferred terms in the dropdown menus that provide suggested terms, when you type into autocomplete fields. This configuration change was carried out via multiple tenant-specific configuration files, one for each type of authority term: Person, Organization, Storage Location, and so on.

The main ("master") configuration file for the Lifesci tenant, lifesci-tenant.xml, contains multiple merge directives that specify that each of these lifesci tenant-specific files is to be merged into its counterpart default configuration file.

You might then take a look at one of these configuration files for the Organization authority, lifesci-authority-organization.xml as an example. Again, its changes are relatively straightforward.

This file matches on a hierarchy of three tags in the default configuration file:

• A top level record tag

• A container instances tag

• Individual vocabulary instance tags

and then for each Organization vocabulary instance matched within that <instances> block, it inserts a new tag, <nptAllowed>false</nptAllowed>, that will be merged into the default configuration file's settings: