Configuring CollectionSpace's Application Layer - An Overview

This document provides an overview of the types of configuration changes you can make in CollectionSpace's Application layer. It also provides basic instructions about where and how you can make such changes.

A CollectionSpace system has three layers. A simplified overview:

• The User Interface (UI) layer. This layer runs in a web browser, and is what your users will see on their screens when working with CollectionSpace.

• The Application layer. This layer consists of compiled code, and runs on your server. It routes and translates data between the UI and Services layers, and orchestrates some complex interactions between those two layers.

• The Services layer. This layer also consists of compiled code, and runs on your server. It stores and provides data relating to your museum's object and procedural records, via a content management system and databases.

The parts of the Application layer of interest to you when configuring CollectionSpace are primarily:

• Configuration files

By editing these XML-based configuration files, you can change many of CollectionSpace's behaviors. Some of these changes can be made exclusively in the Application layer, while others may require corresponding changes in the UI and/or Services layers.

In nearly all instances, the Application layer uses a merge model:

• By default, the Application layer will use the settings in its default configuration files.

• However, if you:

  • Create configuration files in the tenant folder for your museum, containing just your changes to the default settings; and

  • Take a couple of additional steps to declare the presence of these files, and to copy them to the right location

Then, each time that the server starts up, the Application layer will merge in the changes from your own tenant's configuration files into the corresponding default configuration files, thus changing or adding to the default settings.

As described in Configuring CollectionSpace, you will be making your Application configuration changes to the configuration files for your museum; that is, to the configuration files for your tenant. A tenant is a space or partition on a CollectionSpace system for your museum or collection, within which you'll make most or all of your changes.

Some of the important configuration files that you can edit in the Application layer to modify the behavior of your tenant include:

• A host-specific settings file, settings.xml. This file lets you edit settings for your tenant pertaining to the CollectionSpace server: cache settings, URL paths, password reset settings, and the like.
  
  You may need to make minor changes to this file during installation, as per instructions in Installing CollectionSpace, and will rarely need to edit this file again.

• A main ("master") configuration file for your tenant, named {mymuseum}-tenant.xml, where {mymuseum} represents the actual short name of your museum. This file declares all of the Application layer configuration files that affect the behavior of your museum's tenant, and describes how they are to be either merged or included together.
  
  This file includes declarations of CollectionSpace's default configuration files and, optionally, of configuration files specific to your tenant, that can change or add to the default settings.

• Optional configuration files with meaningful names of your own choosing, which reside in your tenant's folder. You'll add these files to change or supplement the default settings (more on this below).

If you haven't already done so, you'll need to do this - just once:

• Create your new tenant. See Creating your new tenant for detailed instructions.
  
  You'll make nearly all of your configuration changes to adapt CollectionSpace for the needs of your museum, in the tenant folder for your museum, within the Application layer source code tree.

• Find your tenant folder within the Application source code tree. See Finding your tenant folder for instructions.

After that, do this just once for each type of record (or other discrete aspect of CollectionSpace's configuration):

• 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.

• 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.

• 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:

  <include src="base-procedure-acquisition.xml"/>

• 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 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:

    <include src="base-procedure-acquisition.xml,{mymuseum}-procedure-acquisition.xml" merge="xmlmerge.properties" />

    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:

    <include src="base-procedure-acquisition.xml,walkerart-procedure-acquisition.xml" merge="xmlmerge.properties" />