unified collectionspace config

What is unified collectionspace config

Configuration document used by UI and App layer to define relationships between the service layer and the UI. Often referred to just as cspace-config

With the addition of the cspace.jar file then these files can also be used by the service layer when it starts up to initialize the schemas

Where is unified collectionspace config

How to check out the Application layer source code
What is multi tenancy

Activating your changes in the UI

Release 1.7 and earlier requires a restart of the webapp to make any changes available. Just touching the collectionspace.war (depending on your tomcat set up) ought to be enough.
Release 1.8 onwards:
You can hot swap config files by just changing the documents that the tarball has deployed (or adding new ones) and going to the following url: [http://]{collectionspaceUrl}/collectionspace/tenant/{tenantname}/init This should force the application to refresh the configuration documents

If you are working from tarball you just need to run the commandline

mvn clean install -DskipTests and if your JBOSS_HOME env is correctly set it will deploy everything for you. however, if you have created a new tenant file make sure you rename it and place it in the same place as the tarball files

Config overlay structure

cspace-config-{tenantname}.xml lists all the procedures, authorities, settings etc that should be used for this specific tenant.
e.g. <include src="base-procedure-loanin.xml"/> this would include the loanin procedure which is described in that file.
the order to try to find the file:
1. tenants/{tenantname}/base-procedure-loanin.xml
2. defaults/base-procedure-loanin.xml

as soon as the file is found it stops looking.

within base-procedure-loanin.xml you will see further includes
e.g. <include src="domain-procedure-loanin.xml" />
which once again it looks for in the following places:
1. tenants/{tenantname/}/domain-procedure-loanin.xml
2. defaults/domain-procedure-loanin.xml

if multiple files are specified in the include tag:
e.g. <include src="local-settings.xml,settings.xml" strip-root="yes"/>
then it splits on the comma and looks for the first file in all of the places as above and then if it doesn't find that goes onto the next file and continues until it finds a file.

if multiple files are specified in the include tag and that tag also includes a 'merge' attribute:
e.g. <include src="settings.xml,local-{tenantname}-settings.xml" merge="xmlmerge.properties" strip-root="yes" />, then it merges the contents of the second file (after the comma) into the first file (before the comma), based on the merge instructions in the file specified in the {{merge= attribute above. (In this example, {tenantname} represents the name of your museum (tenant).) See tomcat-main/src/main/resources/defaults/xmlmerge.properties, within the Application layer source code tree, for the default set of instructions for merging the contents of those two files.

Message bundle overlay key/value pairs

the only different functionality on overlay is with the message bundles in /tenant/{tenantname}/bundle if the named file is missing but there is a file called {filename}-overlay then the system will attempt to do a key value overlay of the content of that file with the default file ( default/bundle/{filename} ) and then will save the file into the tenant folder. This means that the overlay file can be a small subset of the message bundle making it easier to maintain your bundles. The overhead of manually creating this bundle on the fly is managed by only doing it once. If there is a file of the correct name then the -overlay file will be ignored.

It is assumed the format of the message bundle is KEY:VALUE\n

Best Practise

do not change the base- files but instead add a domain file into the tenant specific folder and add any extra schema items there. This relates to the Services Core / Domain model. Where it is envision that the Core files are never altered but the schemas are only extended by use of the domain model. If you do change the base files then it is best to leave the files in default untouched and create a tenant specific one in the tenant folder - this will improve your upgrade story.

Important files to overlay

For each new tenant it is required that the following changes are made:

 <admin>
        <username>admin@core.collectionspace.org</username>
        <password>Administrator</password>
        <tenant>1</tenant>
        <tenantname>{tenantname}</tenantname>
        <cookievalidformins>60</cookievalidformins>
    </admin>

<url>http://{collectionspace service url}:8180/cspace-services</url>
<tenant>
	<name>hearstmuseum.berkeley.edu</name>
	<version>0.1</version>
	<display-name>Phoebe A. Hearst Museum of Anthropology</display-name>
</tenant>
....
<ims-url>http://{collectionspace service url}:8180/collectionspace/tenant/{tenantname}/</ims-url>
        

Structure

<collection-space>
	<version/>
	<settings/>
	<spec/>
</collection-space>

version

simple numeric which must match the number in the app layer code. This exists to ensure the right version of cspace-config is being used with the right version of the code

settings

admin

an area where admin specific information can reside e.g. default login details which is used in password reset

email

an area where information relevant for the sending of emails by collectionspace should be held e.g. smtp server, reply-to address as well as the content of various standard emails

persistence

Service layer information e.g. url and information only required for generating the service schema files

ui

UI specific information e.g. default login page etc

spec

Information about records, procedures and authorities and how they are referenced in the UI and the service layer