Task Description

This document describes how you can add a field to one of CollectionSpace's standard record types: for a Cataloging, Procedure, or Authority Term record.

This particular document uses the example of adding a text field to a Cataloging record. Related documents - to be added - will describe how to add other types of fields: option list fields, date fields, number fields, autocomplete fields for selecting authority terms, and more.

Extension schemas: where you'll add your field

You'll be adding your new field (or fields) within an extension schema. This gives you complete control over the management of your own set(s) of fields, separately and independently from those that come standard with CollectionSpace.

For each standard record type, CollectionSpace comes with a standard schema (set of fields), known as the common schema. Each common schema generally conforms to the SPECTRUM standard.

If you want, you can then supplement the common schemas by creating one or more additional extension schemas. Each extension schema contains a set of additional fields you want to add to a particular record type, where these fields should (by convention and best practices) be either:

• Pertinent to your community of practice (from anthropology and art history to zoology), and potentially usable (and even collaboratively maintainable) by multiple museums within that community
  or

• Specific to your own museum or collecting institution.

As an illustrative example, you might:

• Add an extension schema to Cataloging records, containing fields specific to describing your museum's objects.

• Add two extension schemas to Acquisition records: one containing fields pertinent to how your community of practice generally handles the process of acquiring objects, and a second containing fields specific to your museum's acquisitions data.

• Add an extension schema to Loan Out records, containing fields specific to your museum's loans data.

Prerequisites

This work requires knowledge of how to:

• Make new directories, copy files, and perform similar tasks in your operating system.

• Run commands at your operating system's command prompt.

• Edit text files.

• Edit HTML files.

• Edit XML files.

In addition, if you have not already done so:

• Create a tenant for your museum. (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 configuration changes.)

  • For details, please see Creating your new tenant

• Read an overview of how to make configuration changes in CollectionSpace's Application (UI) layer.

  • For details, please see Configuring CollectionSpace's Application Layer - An Overview

• Read an overview of how to make configuration changes in CollectionSpace's User Interface (UI) layer.

  • For details, please see Configuring CollectionSpace's User Interface (UI) Layer - An Overview

Layers involved

To carry out this task, you will need to make changes in the following CollectionSpace layer(s):

• Application

• User Interface (UI)

In addition, you will need to run a single command in the following CollectionSpace layer:

• Services

Procedure

Application layer

Find your tenant folder in the Application layer

(Or instead see Finding your tenant folder.)

Find or create the relevant configuration file within your tenant folder

Edit that file to add your extension schema and its new fields

• Edit the relevant Application layer configuration file in your tenant folder you want to change (within tomcat-main/src/main/resources/tenants/{mymuseum}) in a text editor, to add XML markup for:

  • Your extension schema

  • Any fields you want to add inside that schema.

Add a tag for your extension schema

The markup to create an extension schema requires just a single XML tag, of the form:

By convention, the schema name should:

• Start by including the record type (matching the record type, whether plural or singular, specified in the common schema)

• Contain underscores as word separators

For instance, persons_naturalhistory would be a suitable name for an extension schema that adds fields to the Persons record for the natural history community of practice (domain), and acquisitions_mymuseum could be used to name an extension schema that adds fields to the Acquisition record that are specific (local) to the museum named mymuseum.

By convention, as well, the schema URL should be of the form:

For instance:

Add a tag for your new field in that extension schema

The markup to add a field depends on the type of field you're adding: plain text, date, number, and the like. Here's an example of a tag that adds a simple plain text field, within the two example extension schemas above:

The value of the section="" attribute for your field should match the value of the <services-record-path id="" attribute for your extension schema, in order to associate your field with your extension schema.

By adding this <field> tag below the <services-record-path> tag shown above, you will now have the following contents in your configuration file, for each of the two examples above:

Add wrapper tags to ensure your new extension schema and field(s) are merged into the correct place

You also need to add 'wrapper' tags within the relevant Application layer configuration file in your tenant folder, to ensure that the new extension schema you've added, as well as any fields you've added to that schema, are merged into the correct place within the corresponding default configuration file.

Often, this can be as simple as:

• Adding a top-level <record id=""> tag, at the top of that file. (That tag should be identical to the top-level tag in the default configuration file into which you'll be merging your changes.)

• Adding a corresponding </record> closing tag, at the bottom of that file.

• Adding a <section id=""> tag, above the field(s) you're adding. (That tag should be identical to one of the <section> tags in the default configuration file into which you'll be merging your changes, and preferably identical to a <section> tag that contains existing field(s) that are at least somewhat related to the ones you're adding.)

• Adding a corresponding </section> closing tag, below the tags for the field(s) you're adding.

By adding these <record id="">...</record> and <section id="">...</section> wrapper tags, you will now have the following contents in your configuration file, for each of the two examples above: