Synchronizing Authority/Vocabulary Terms with another CollectionSpace Instance

Owned by Jessi Weithman
Apr 18, 2024

Purpose

Starting with v4.4, CollectionSpace supports limited functionality for synchronizing authorities and term lists (aka vocabulary lists) with another CollectionSpace instance.  This allows sharing of authority and vocabulary terms between CollectionSpace instances, ensuring consistency of terms across CSpace instances with shared collection types, profiles, or other collaborative aims.

How it Works

  • A specific CollectionSpace instance is designated as the authority term server. One or more CollectionSpace instances can be designated as clients of the server.
  • Authority terms can be added to or updated in the authority term server instance and these terms can then be synchronized (added and updated) to the clients.
  • Each client (not the server) is responsible for initiating synchronization of its individual authority term lists -following a "pull" model.
  • Follow the configuration instructions below to designate which authorities on the client(s) that you want to support synchronization.
  • After each successful synchronization, the client(s) will contain any new terms or updated terms found on the authority term server.
  • Things to note:
    • All sync'd terms and the authority itself will become read only on the client side after sync
    • If you would like users to be able to access sync'd/shared terms of a specific authority type as well as add terms of that type, you will need to create two or more authorities instances of that type -for example, one "shared" Person authority and one "local" Person authority.

Client Configuration

Configuring each authority for synchronization

If you plan on having a client attempt to synchronize an authority type, ensure the following XML snippet is in the client's Application layer's base configuration file for that authority type (term/vocabulary list).

 <supportsReplicating>true</supportsReplicating>
 <remoteClientConfigName>default</remoteClientConfigName>

For example, to enable a client to synchronize Place authorities, add the XML snippet above to this Application layer config file:

application/tomcat-main/src/main/resources/defaults/base-authority-place.xml

If an authority/term-list's configuration record does not contain the "supportsReplicating" element, CollectionSpace assumes a value of 'false' meaning the authority/term-list cannot be synchronized.

Here is an excerpt from what the config for the Place authority should look like:

<record id="place" type="authority" cms-type="default" generate-services-schema="true">
    <terms-used>true</terms-used>
    <web-url>place</web-url>
    
    <services-tenant-auth-singular>Placeauthority</services-tenant-auth-singular>
    <services-tenant-auth-plural>Placeauthorities</services-tenant-auth-plural>
    <services-tenant-singular>Place</services-tenant-singular>
    <services-tenant-doctype>Placeitem</services-tenant-doctype>
    ...
    <services-url>placeauthorities</services-url>
    <authority-vocab-type>PlaceAuthority</authority-vocab-type>
    <hassoftdelete>true</hassoftdelete>
    <supportsReplicating>true</supportsReplicating>
    <remoteClientConfigName>default</remoteClientConfigName>
    ...
<record>
Configuring which authority term server to synchronize with

To specify the "server" and read-only credentials with which to synchronize, add the following XML snippet to the tenant's settings.xml file in the Application layer sources.  For instance, the Public Art Profile's settings.xml file can be found here:

    application/tomcat-main/src/main/resources/tenants/publicart/settings.xml

Here is an example definition for the <remoteclients> configuration element taken from the default "core" tenant's settings.xml file:

<remoteclients>
	<remoteclient>
		<name>default</name>
		<url>http://localhost:8180/cspace-services/</url>
		<user>admin@testsci.collectionspace.org</user>
		<password>Administrator</password>
		<ssl>false</ssl>
		<auth>true</auth>
		<tenantId>2</tenantId>
		<tenantName>testsci.collectionspace.org</tenantName>
	</remoteclient>
</remoteclients>

This snippet shows the configuration for the <remoteClientConfigName> named "default".  Any authority or term-list that is configured with 

<remoteClientConfigName>default</remoteClientConfigName> in its record configuration will try to sync with the server specified inside the <url> element using the credentials <user> and <password>.

You can configure multiple servers from which to synchronize by adding another <remoteclient> element and ensuring the <name> value is unique.  The configuration file for an authority type (e.g., "base-authority-place.xml" can specify a specific client by using the name value.  For example, the following config files setup the Place authority to synchronize with the server with the config named "PAConfig"

application/tomcat-main/src/main/resources/tenants/publicart/settings.xml

<remoteclients>
	<remoteclient>
		<name>default</name>
		...
		<tenantName>testsci.collectionspace.org</tenantName>
	</remoteclient>
    <remoteclient>
		<name>PAConfig</name>
		<url>http://sas.pa.org:8180/cspace-services/</url>
		<user>admin@sas.pa.org</user>
		<password>Administrator</password>
		<ssl>false</ssl>
		<auth>true</auth>
		<tenantId>2</tenantId>
		<tenantName>sas.pa.org</tenantName>
	</remoteclient>
</remoteclients>

application/tomcat-main/src/main/resources/defaults/base-authority-place.xml 

<record id="place" type="authority" cms-type="default" generate-services-schema="true">
    <terms-used>true</terms-used>
    <web-url>place</web-url>
    
    <services-tenant-auth-singular>Placeauthority</services-tenant-auth-singular>
    <services-tenant-auth-plural>Placeauthorities</services-tenant-auth-plural>
    <services-tenant-singular>Place</services-tenant-singular>
    <services-tenant-doctype>Placeitem</services-tenant-doctype>
    ...
    <services-url>placeauthorities</services-url>
    <authority-vocab-type>PlaceAuthority</authority-vocab-type>
    <hassoftdelete>true</hassoftdelete>
    <supportsReplicating>true</supportsReplicating>
    <remoteClientConfigName>PAConfig</remoteClientConfigName>
    ...
<record>
Performing Synchronization

To perform a sync, you'll need to send the client a synchronization request via the CollectionSpace RESTFul API.  Here is an example using the Linux cURL command to to send a request to a client for it to synchronize itself with the configured (see above) authority term server:

 curl -X POST -i 'http://localhost:8180/cspace-services/personauthorities/urn:cspace:name(person)/sync' -u admin@core.collectionspace.org:Administrator
Synchronization Options

You can use the following HTTP request query parametersimp when making a sync request:

 

impTimeout

forceUpdate

 

Â