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.

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.

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.

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.

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" />
```

And then ... repeat the following steps, until you are satisfied with the results:

Make changes to your tenant's configuration
Copy your changes to the CollectionSpace server
Generate equivalent Services layer files and copy them to the CollectionSpace server
Test your changes

Make changes to your tenant's configuration

Edit your tenant's relevant configuration files to make your desired changes from the default behavior. You can make changes to record- and field-level settings, vocabularies and more.

Each of your tenant's configuration files will allow you to make changes to a specific record type or a discrete aspect of CollectionSpace's functionality. Your settings in each file will then be merged into its corresponding default configuration file.

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.

Copying your changes to the CollectionSpace server

Unknown macro: {multi-excerpt}

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:
```
mvn clean install -DskipTests
```

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

Generate equivalent Services layer files and copying them to the CollectionSpace server

Unknown macro: {multi-excerpt}

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
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:
```
ant deploy_services_artifacts
```
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.

Can you skip generating equivalent Services layer files?

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.:
```
 
```

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.

Test your changes

In your Web browser, visit or reload the specific page(s) whose Application layer configurations you've modified, to see the effects of your changes.

If you don't see your changes reflected

If you don't see the configuration changes you made reflected on your pages, try the following steps, in succession:

Reinitialize the Application layer

Visit your tenant's Sign In (login) page in your web browser.
Log in to your tenant as an administrative user. For details, see the Test section of Creating your new tenant.
Any time after you are logged in, enter the following URL (after your hostname and port) to reload Application layer configuration files for your tenant:
```
 
```
(Be sure to substitute the actual short name of your museum for {mymuseum} in the URL above.)
For instance, if your museum's short name was walkerart, and your server was running on localhost at port 8180, you might enter:
```
 
```
Clear your web browser's caches.
Using your web browser:
- Visit your tenant's Sign In (login) page.
- Log into your tenant.
- Visit the specific page(s) whose Application layer configurations you've modified.
- Reload those page(s) 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.

Shut down and restart the CollectionSpace servers

Shut down the CollectionSpace servers
Start up the CollectionSpace servers.
Clear your web browser's caches.
Using your web browser:
- Visit your tenant's Sign In (login) page.
- Log into your tenant.
- Visit the specific page(s) whose Application layer configurations you've modified.
- Reload those page(s) 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.

Check how your changes were merged into the default settings

If you still don't see your changes reflected, or if changes occurred but they're not what you expected:

Unknown macro: {multi-excerpt-include}

(Re)generate equivalent files in the Services layer

Try generating (or regenerating) the equivalent files in CollectionSpace's Services layer.

If you've accidentally skipped this step, and some of the changes you've made in the configuration files in your tenant folder, in the Application layer, required that Services layer files be updated to match those changes, this could result in your not seeing your changes reflected or other unexpected behavior.

CollectionSpace Unreleased Documentation