How to add a term to a dynamic term list

Owned by Jessi Weithman
Apr 18, 2024
4 min read

Work remaining:

  • General review of this document to ensure that it is still valid
  • The instructions on the option to send an HTTP POST request to add a new term to a controlled list need to be checked, to confirm they still work as described in a multi-tenant environment. We also might decide where those instructions might reside - do they go into a "data import" document in the Using Collectionspace section, or stay in this Configuring CollectionSpace section?

How to add a term to a controlled list

A term list (also called a "pick list") is a limited set of terms arranged in a simple alphabetical order or in some other logically evident way. Lists are usually short and used to describe aspects of content objects or entities which have a limited number of possibilities. Examples include geography (country, state, city), language (English, French, Swedish), or format (text, image, sound). In CollectionSpace, controlled lists are also called Basic Vocabularies or Enumerations. Controlled lists appear in the User Interface (UI) as drop-down lists, as illustrated next:

Each term within a list, like Enquiry, Commission, and Loan shown above, is an instance that is also referenced in other records, as illustrated next: collection-space/spec/records/@id=acquisition

<field id="acquisitionFundingCurrency" autocomplete="vocab-currency" ui-type="enum">
<enum-default>US Dollar</enum-default>
<selector>.csc-acquisition-acquisition-funding-denomination</selector>
</field>

The purpose of this document is to provide instructions on how to add additional terms to a list of this type.

Task Description

Adding a term to a controlled list requires no changes in any of the layers, but does require an alteration to the cspace-config.xml document or could include a JSON call to the application layer. Using either method you can add additional terms to a list.

Prerequisites

A system administrator with appropriate permissions can add terms to an existing flat vocabulary or controlled list. The user should have experience editing XML and HTML files.

Procedure

There are two ways of adding a new term to a controlled list. They are shown in the next sections.

Using the Option tag

Follow the next steps to add a term to a controlled list using the option tag:

1. Open the cspace-config collection-space/spec/records/@id=vocab and locate within it the code for instances, as illustrated next:

<instance id="vocab-currency">
<web-url>currency</web-url>
<title-ref>currency</title-ref>
<title>Standard Currency</title>
<options>
<option id="USD">US Dollar</option>
<option>Canadian Dollar</option>
<option>Euro</option>
<option>Pound Sterling</option>
<option>Danish Krone</option>
<option>Swedish Krona</option>
<option>Swiss Franc</option>
</options>
</instance>

In the above example, the autocomplete=instance ID identifies which controlled list type to use. In this example, ui-type="enum" specifies that this list is a non-editable drop-down list (this is currently the only option supported for controlled lists).

2. To add a new item or field to a controlled list, enter a new term name between option tags within the instance tag.

<option>New currencyfield</option>

Important Note

If ID is specified, than it is used; otherwise, the ID is created from the value, after it has been lowercased and any spaces removed.

3. Then, after first logging into the UI chain, redeploy the collectionspace.war and run this command.

  • In your web browser, visit collectionspaceURL/collectionspace/ui/{tenantname}/html/ and log in as you must have a valid cookie set.
  • Paste collectionspaceURL/collectionspace/tenant/{tenantname}/vocabularies/{web-url}/refresh into your browser - in the example web-url = currency.

This step adds any missing values to this vocabulary, as defined in cspace-config.xml.

Using a JSON object

The second way is adding a new term to a controlled list is by the POST of a JSON object, as illustrated next:

{'fields' : {'displayName' : 'New currencyfield' } }

POST to /tenant/{tenantname}/vocabularies/{instance web url}/ For example, /tenant/core/vocabularies/currency/

Test

You can test by either of two methods:

  1. Go to the site and see if the new term appears in the UI
  2. Go to the URL /tenant/{tenantname}/vocabularies/{instance web URL} For example, /tenant/{tenantname}/vocabularies/currency
    and, if you have a session ID from logging into the UI, you should get  a JSON object that has your new term in it, for example:
{
    "items": [{
        "summary": "Euro",
        "number": "Euro",
        "csid": "2954fd45-dbb4-4089-951a",
        "authorityid": "17375200-674c-4759-83e9",
        "displayName": "Euro",
        "refid": "urn:cspace:org.collectionspace.demo:vocabulary:id(17375200-674c-4759-83e9):item:id(2954fd45-dbb4-4089-951a)'Euro'",
        "recordtype": "currency"
    },
    {
        "summary": "Canadian Dollar",
        "number": "Canadian Dollar",
        "csid": "bca64954-b46c-4f87-9adf",
        "authorityid": "17375200-674c-4759-83e9",
        "displayName": "Canadian Dollar",
        "refid": "urn:cspace:org.collectionspace.demo:vocabulary:id(17375200-674c-4759-83e9):item:id(bca64954-b46c-4f87-9adf)'Canadian+Dollar'",
        "recordtype": "currency"
    },
    {
        "summary": "Swiss Franc",
        "number": "Swiss Franc",
        "csid": "0843d8b6-4e4c-4206-a7ba",
        "authorityid": "17375200-674c-4759-83e9",
        "displayName": "Swiss Franc",
        "refid": "urn:cspace:org.collectionspace.demo:vocabulary:id(17375200-674c-4759-83e9):item:id(0843d8b6-4e4c-4206-a7ba)'Swiss+Franc'",
        "recordtype": "currency"
    },
    {
        "summary": "Danish Krone",
        "number": "Danish Krone",
        "csid": "daf112c8-da84-4999-b43d",
        "authorityid": "17375200-674c-4759-83e9",
        "displayName": "Danish Krone",
        "refid": "urn:cspace:org.collectionspace.demo:vocabulary:id(17375200-674c-4759-83e9):item:id(daf112c8-da84-4999-b43d)'Danish+Krone'",
        "recordtype": "currency"
    },
...

    {
        "summary": "New currencyfield",
        "number": "New currencyfield",
        "csid": "33c56b8a-f5d1-4f84-8a2a",
        "authorityid": "17375200-674c-4759-83e9",
        "displayName": "New currencyfield",
        "refid": "urn:cspace:org.collectionspace.demo:vocabulary:id(17375200-674c-4759-83e9):item:id(33c56b8a-f5d1-4f84-8a2a)'New+currencyfield'",
        "recordtype": "currency"
    }]
}

Summary

Using one of the two methods shown above, a new term is added to the controlled list and becomes available when a user logs onto CollectionSpace and edits a record that uses that controlled list.

See Also

Additional information is available in the following documents: