Using Extensions and Profiles

Owned by Chad Nelson (Unlicensed)
Oct 02, 2015

What to Expect

This guide will show you how to install the optional Extension Sets and Profiles that are included with the core CollectionSpace code. This will allow you to quickly add new functionality based on the guidelines from domain specialist and communities of practice. You will need source code for the application, services, and UI layers in the same directory which will be referred to as /path/to/source/.

All commands listed will be assumed be run on Ubuntu 14.04.

About Extension Sets and Profiles

Extension sets

An extension set is XML configuration files and HTML templates bundled together to add new fields or groups of fields to existing cataloging, procedure, or authority form.

As of Release 4.2, available Extensions are:

Profiles

Profiles include one or more Extension Sets plus further configuration and templates to update existing fields or field groups. These can include:

  • Updating Data Entry workflow to surface fields and sections most relevant to a community of practice.
  • Updating controlled vocabularies and field labels to use terms preferred by that community of practice.

As of Release 4.2, available Extensions are:

Installing and Using Extension Sets and Profiles

All the code required to install and use extension sets and profiles is already included with the core CollectionSpace software. This code is in both the Application layer (XML configuration) and the UI Layer (HTML templates & plain text messages files).

In the application layer, profile and extension set files can be found in the /path/to/source/application/tomcat-main/src/main/resources/defaults/extensions/directory. Files for an extension set or profile follow a naming convention to identify which extension they belong to and which part of CollectionSpace they extend. For example, files in the Variable Media extension set are:

  • variablemedia-collectionobject.xml
  • variablemedia-procedure-conditioncheck.xml
  • variablemedia-vocabularies.xml

Similarly, profiles follow the same convention, so for the Fine and Contemporary Art Profile:

  • fcart-profile-collectionobject.xml
  • fcart-profile-procedure-media.xml

Enabling in the Application layer

The tenant configuration file is modified to enable an extension set and/or profile. For more information on creating your custom tenant, see Creating your new tenant.

If the tenant's shortname is demo, the tenant configuration is at:

  /path/to/source/application/tomcat-main/src/main/resources/demo-tenant.xml 

Editing that file, we will indicate that we want to merge the extension files with the base configuration definitions.   First we'll update the collection object configuration. Find the following line:

<include src="base-collectionobject.xml"/>

If we want to enable the Variable Media Extension , we would update it with a path to the variable media collection object extension file, as well as adding the merge attribute. More information about configuration merging can be found in Merging your changes into CollectionSpace's Application layer.

<include src="base-collectionobject.xml,extensions/variablemedia-collectionobject.xml"
         merge="xmlmerge.properties"/>

If we wanted to enable the full Fine and Contemporary Art Profile, which includes the Variable Media Extension, the Fine Art Extension, plus vocabulary updates, we would edit to become:

<include src="base-collectionobject.xml,extensions/variablemedia-collectionobject.xml,extensions/fineart-collectionobject.xml,extensions/fcart-profile-collectionobject.xml" 
         merge="xmlmerge.properties"/>

We would then follow the same process for all all other configuration files for that extension or profile, which you can identify by the naming convention or on Required Files for Profile and Extension.

So for example, part of the Fine Art Extension is the citation authority configuration. We'd look for the line: 

<include src="base-authority-concept.xml" />

and update it to:

<include src="base-authority-concept.xml,extensions/fineart-authority-concept.xml"
         merge="xmlmerge.properties" />

The final piece of the application configuration is to update which vocabularies are included. To do this we need to replace an empty domain-instance-vocabularies.xml in our demo tenant, or merge the contents of extension vocabularies into the domain-instance-vocabularies.xml file. To do this, we'll copy the file from the defaults directory into our tenant directory. 

cp -i /path/to/source/application/tomcat-main/src/main/resources/defaults/domain-instance-vocabularies.xml /path/to/source/application/tomcat-main/src/main/resources/tenants/demo/domain-instance-vocabularies.xml

The -i option on the copy command will warn you before overwriting an existing file.  Now we'll updated the copied  /path/to/source/application/tomcat-main/src/main/resources/tenants/demo/domain-instance-vocabularies.xml,  adding one line to include the variable media extension vocabularies configuration.

<root>
    <include src="extensions/variablemedia-vocabularies.xml" strip-root="yes" />
</root>

For Profiles, it will be a little more complicated. For example, with the Fine and Contemporary Art Profile, in addition to overriding the domain-instance-vocabularies.xml to include vocabularies for both Variable Media and Fine Art , we also need to update the tenant config to use the fcart-profile base vocabulary. So in  /path/to/source/application/tomcat-main/src/main/resources/demo-tenant.xml we'll find the line:

<include src="base-vocabularies.xml"/>

and update it to:

<include src="extensions/fcart-profile-vocabularies.xml"/>

 

And now that we have completed the application layer, we'll move onto the UI layer.

Enabling in the UI Layer

 In the UI layer, extension and profile files can be found in the src/main/webapp/extensions. Following the convention of the UI layer, files are split into the bundle directory, which contains updates to field labels, and the html directory which contains the updated templates. 

For extension sets, we only need to worry about the templates, as field labels are included in the core configuration. 

To enable the variable media templates, we will simply copy them to our UI tenant to override the default tenant. We'll start with the Cataloging template (which corresponds to the collection object configuration in the application layer):

cp /path/to/source/ui/src/main/webapp/extensions/html/templates/variable-media-extension/CatalogingTemplate.html /path/to/source/ui/src/main/webapp/tenants/demo/html/pages/CatalogingTemplate.html

and then the same for the condition check template:

cp /path/to/source/ui/src/main/webapp/extensions/html/templates/variable-media-extension/ConditioncheckTemplate.html /path/to/source/ui/src/main/webapp/tenants/demo/html/pages/ConditioncheckTemplate.html

With those file copied over, we just now need to deploy the changes to our tomcat server.

 In addition to complete drop-in replacement templates, snippets of the HTML required for each field added in an extension set is also provided. This is to allow you to drop the fields into your already customized templates. These snippets can be found in the

/path/to/source/ui/src/main/webapp/extensions/html/snippets directory.

 Working with Profiles in the UI is exactly the same process, except we'll also need to override some field labels.

For the Fine and Contemporary Art Profile, we need to copy the template into our UI tenant and update the UI tenant bundle/core.messages-overlay. We'll start with the templates, which we can just copy over as a group.

cp /path/to/source/ui/src/main/webapp/extensions/html/templates/fine-and-contemporary-art-profile/* /path/to/source/ui/src/main/webapp/tenants/demo/html/pages/

Next we will update the field labels by copying the text in src/main/webapp/extensions/fcart-profile-core-message.properties and appending to your existing tenants src/main/webapp/tenants/demo/bundle/core-messages.properties-overlay. You could do this quite easily with:

cat /path/to/source/ui/src/main/webapp/extensions/fcart-profile-core-message.properties >> /path/to/source/ui/src/main/webapp/tenants/demo/bundle/core-messages.properties-overlay

Deploying Extension set changes

Deploying extension set changes follows the usual build process. We'll use maven to build the compiled webapps and the then ant to enable those changes.

From the base directory containing the source code for application, services, and ui:

 

#shutdown tomcat
$CSPACE_JEESERVER_HOME/bin/shutdown.sh

cd /path/to/source
 
cd application
mvn clean install -DskipTests
 
cd ../ui
mvn clean install -DskipTests 
 
cd ../services
mvn clean install -DskipTests 
ant undeploy deploy
 
#Start tomcat back up
$CSPACE_JEESERVER_HOME/bin/startup.sh

Your newly updated tenant will now be available, with additional fields in the Cataloging and Condition Check forms. If you are not seeing the new fields, you might need to clear cached content from your browser.