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.

Contents

Overview

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.

How the settings in your museum's configuration files are merged into the default settings

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.

If you have needs that go beyond the standard set of rules, you can specify your own XMLMerge properties file, containing your own individually customized set of rules for any particular merge, between a configuration file containing default settings and a corresponding configuration file containing your museum's settings.

You can learn more about XMLMerge and its properties files in the fairly extensive XMLMerge README documentation.

Example scenarios for merging in your museum's settings

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:

Scenario: Adding fields to a record

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.

Scenario: Changing behavior related to non-preferred terms in vocabularies

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:

Testing your merged changes

Unknown macro: {multi-excerpt}

When the CollectionSpace servers start up, the merged state of Application layer configuration settings - the default settings, plus any changes that are being merged in from files in various tenant folders - are written to log files in $CSPACE_JEESERVER_HOME/temp (or %CSPACE_JEESERVER_HOME%\temp under Windows).

As an example, the log file merged-base-authority-citation.xml_lifesci-authority-citation.xml-.xml represents the output from the merger of the default configuration file, base-authority-citation.xml, with a merge file in the Lifesci tenant folder, lifesci-authority-citation.xml, containing changes to that default file's settings.

You can view these log files to determine if the changes you've made to Application layer settings, in configuration files in your tenant folder, are being merged into the default configuration files in the way that you are expecting.

Alternatives to merging: other ways of making configuration settings changes for your museum

An alternative and complement to merging: includes files

Built into the Application layer's processing of its configuration files is an alternative mechanism for configuring its settings. This mechanism, which uses "includes files," is still supported, alongside the merge model described above.

Within most or all of the configuration files in the Application layer's defaults folder, are tags similar to this one, found in the default configuration file for Loan Out records:

This means that, if you take a default configuration file, such as base-procedure-loanout.xml, from within the defaults folder, 'clone' (copy) that file into your tenant folder, and change base to domain at the start of its name (e.g. domain-procedure-loanout.xml), this would then become an "includes" file.

The contents of this "includes" file will be included, or inserted, at the location of the <include> tag in its corresponding 'base' file, giving you another way to make changes specific to your museum, to supplement the settings in the Application layer's default configuration file for a particular record type or other discrete unit of configuration.

"Includes" files are easier to use than merge files, as it can sometimes require multiple tries to "get the merge right," especially with complex changes. In contrast, merge files make it possible for you to override default settings: you can selectively change and even delete settings in the default configuration file. "Includes" files can merely add new settings - such as new fields - alongside the defaults.

"Includes" files are complements, as well as alternatives, to merge files. You can selectively choose either merge files or includes files for different record types, or even use both of them together for a particular record type, if you wish. The contents of an "includes" file will be included at its specified location after the merge occurs.

An alternative to merging: overlay files

Built into the Application layer's processing of its configuration files is a second alternative mechanism for configuring its settings. This mechanism, which uses "overlay files," is still supported, alongside the merge model and "includes" files described above.

Each overlay file replaces all of the settings of a single default configuration file with its own settings. To create an overlay file, you will:

Set this up by editing the main ("master") configuration file for your tenant, specifying which file(s) overlay which other file(s).
Copy the relevant default configuration file from the defaults folder into the folder for your own tenant.
Rename that file to give it the name of an overlay file you previously entered in the main configuration file.
Make your changes in that overlay file.

To set up the use of overlay files, you'll edit the main ("master") configuration file for your tenant. Starting at the top-level application folder for the Application layer source code tree, you'll find this main configuration file in /tomcat-main/src/main/resources/{mymuseum}-tenant.xml, where {mymuseum} represents the actual short name of your museum.

By default, most of the entries in that file each reference a single base- configuration file; for example:

However, if you edit one or more of these entries to include a comma-separated list of configuration files, you will set up an overlay mechanism specifically for that particular record type (or other discrete unit of configuration listed in the main configuration file). E.g.:

This entry specifies that settings will be used from whichever of the files mymuseum-procedure-intake-overlay1.xml, mymuseum-procedure-intake-overlay2.xml, and base-procedure-intake.xml is found first, in that order. And that means that, if you add a mymuseum-procedure-intake-overlay1.xml or mymuseum-procedure-intake-overlay2.xml file to your tenant folder, it will overlay (replace outright) the settings in the default configuration file, base-procedure-intake.xml:

There are a number of reasons for strongly preferring the merge mechanism over the overlay mechanism. Among these, merge files:

Help document the changes that you've made from the defaults, because your merge file will only include changes ("deltas"), rather than duplicating nearly all of the content from the defaults.
Are somewhat more resistant to future changes, if any, that might be made to the default configuration files in newer versions of CollectionSpace.

Overlay files can be used together with includes files for specific record types. As long as you keep the <include src="domain-..." strip-root="yes"/> tag in your overlay files, that will still bring in any supplementary configuration you've put in your includes files.

However, overlay files don't work with the merging mechanism. That is, for any specific record type, you will either need to use merge files or overlay files.