/
Configuring CollectionSpace's Application Layer - An Overview

Configuring CollectionSpace's Application Layer - An Overview

Mar 25, 2015

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.

About CollectionSpace's three layers

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.

About configuring the Application layer

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.

The merge model for Application layer configuration

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.

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.

Making your changes in your tenant folder within the Application layer

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.

Important Application layer configuration files for your tenant

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.

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.

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

Configuring the Application layer for your museum

Prepare to make your changes

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.

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

 

 

 

 

 

 

Unknown macro: {multi-excerpt}
  • 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.

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.

 

 

 

 

 

 

 

 

 

 

Unknown macro: {multi-excerpt}
  • 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.