How to add a dynamic term list

Task Description

This document describes how you can add a dynamic term list that can be used in a Cataloging, Procedure, or Authority Term record.

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

Layers involved

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

• Application

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

Dynamic term lists are added in the domain-instance-vocabularies.xml file at the root of your Application layer tenant folder.  (This is the same location as your tenant's settings.xml file.)  If this file does not exist, create a new, empty text file in that folder with that name.

Edit that file to add your new dynamic term list

• If this is the first dynamic term list you are adding to domain-instance-vocabularies.xml, then add <instances> and </instances> to the top and bottom of the file.

• The markup to create a dynamic term list requires a instance element:

<instance id="vocab-{brief vocabulary name}">
	<web-url>{brief vocabulary name}</web-url>
	<title-ref>{brief vocabulary name}</title-ref>
	<title>{display name of vocabulary}</title>
	<options>
		<option id="{brief term identifier}">{term meaning}</option>
		<option id="{brief term identifier}">{term meaning}</option>
		<option id="{brief term identifier}">{term meaning}</option>
		....
	</options>
</instance>

The 'brief vocabulary name' is the identifier used when you use the field in the Many dynamic term lists can be created in the domain-instance-vocabularies.xml file, each in their own <instance> ... </instance> block.

Example of a complete domain-instance-vocabularies.xml file

<!-- The wrapper tag -->
<instances>

<!-- Each dynamic term list is contained in an 'instance' block -->
    <instance id="vocab-approvalState">
        <web-url>approvalState</web-url>
        <title-ref>approvalState</title-ref>
        <title>Approval States</title>
        <options>
            <option id="yes">Yes</option>
            <option id="no">No</option>
            <option id="pending">Pending</option>
            <option id="notrequired">Not Required</option>
        </options>
    </instance>

<!-- Another dynamic term list can follow -->
    <instance id="vocab-exitMethod">
        <web-url>exitMethod</web-url>
        <title-ref>exitMethod</title-ref>
        <title>Exit Method</title>
        <options>
            <option id="courier">Courier</option>
            <option id="inperson">In Person</option>
            <option id="post">Post</option>
        </options>
    </instance>

</instances> 

The domain-instance-vocabularies.xml file is automatically processed when the application layer and service layers are built.  The file in your tenant directory will override the file with the same name in the defaults directory (which is typically a file no dynamic term list definitions.

Build the Application layer

(Or instead see Configuring CollectionSpace's Application Layer - An Overview.)

Services layer

Run a command to generate Services artifacts for your extension schema

Test

After following the procedure above, use a web browser for the following steps:

• First, clear your Web browser's caches.
• If you are not already logged into your museum (tenant) on your CollectionSpace system:
  • Visit your museum's (tenant's) login page. For details, see the Test section of Creating your new tenant.
  • Login as a user in your museum (tenant).
• Navigate to the Administration page
• Select the Term List Management tab
• Find the brief vocabulary name in the Term List Name table
• Select the brief vocabulary name
• Add term values to the repeating "Terms (Values)" table
• Save the term list details

If it doesn't work

....