Skip to end of metadata
Go to start of metadata

Documentation and installation

Documentation for CollectionSpace version 4.0, including downloading and installation instructions.


CollectionSpace's version 4.0 release includes two feature enhancements - one highly significant, hence the 4.0 designation - and several bugfixes. The major features of this release are:

  • Streamlining and simplification of a key part of the process through which you configure CollectionSpace for your museum, known as Unified Configuration. This streamlining should make your configuration work faster, easier, and far less subject to error.
  • The addition of a Work Authority, to cite cultural works.

Release date and schedule

CollectionSpace version 4.0 was released on October 1, 2013.

July 3, 2013: Development Begins
September 13, 2013: Development Ends
September 16, 2013: QA Testing Begins
September 30, 2013: QA Testing Ends
October 1, 2013: Release
October 3, 2013: Formal Announcement to the Community

Release notes

New functionality

Streamlining and simplification of field-level configuration (CSPACE-5615)

Version 4.0 introduces changes which streamline and simplify the process through which you configure fields in CollectionSpace's main record types, as well as how you perform some other general configuration. As a result of these changes, collectively known as Unified Configuration, you can create extension schemas to add new fields specific to your museum and/or community of practice, or change the behavior of existing fields, within a particular record type (Cataloging, Media Handling, Loan Out ...) often by editing just a single XML-based configuration file and its corresponding HTML template file. After doing so, you can then run a quick, automated task to generate all of the other artifacts required to reflect that change.

Prior to these changes, to add new fields and to make certain behavioral changes to existing fields, you also needed to make additional changes within a number of XML-based configuration, schema, and Nuxeo 'document type' files in CollectionSpace's Services layer. Those changes were often fairly technical in nature, and could potentially be error-prone. Now, these Services layer files are all generated automatically, from relatively simple changes made to configuration files in CollectionSpace's Application layer.

Work Authority (CSPACE-6116)

A new Work Authority is now available. This authority allows you to create controlled vocabularies for terms referring to specific cultural works, including built works (e.g. architecture), movable works (e.g. paintings and sculpture), performing and performance art works, moving image works (e.g. motion pictures, television shows), literature, and more.

The Work authority is a community contribution, contributed by Jesse Martinez, a CollectionSpace consultant to the Walker Art Center. It joins CollectionSpace's existing authorities: Citation, Concept, Organization, Person, Place, Storage Location, and Taxon.

User interface improvements

Improved messages when running ant import to seed access permissions (CSPACE-4980)

A user interface improvement was made with the goal of modestly improving part of the installation and setup experience for system implementers and administrators. When running ant import in CollectionSpace's Services layer to 'seed' an initial set of roles, access permissions, and other authorization-related data for one or more tenants (museums), the messages emitted by that command are now far more helpful. Status messages are clearer, routine warnings have been suppressed, and progress information is displayed for long-running operations.

Ease-of-use improvements when configuring your tenant (CSPACE-6204, CSPACE-6206, and CSPACE-6207)

Supplementing the sweeping functionality improvements described above, the combined changes made in these three issues help make it more feasible to put just your museum's changed settings into an 'overlay' file, rather than having to copy every possible setting into that file when making changes. That makes it easier to identify the configuration changes you've made that are specific to your museum, and to carry forward those changes in migrations to future versions of CollectionSpace:

  • When changing the general administrative settings related to your tenant, including hostnames, URLs, and other such settings, you can now configure nearly all of these within your museum's overlay file. As well, you can specify these changes 'sparsely,' by adding only the settings that you've changed to that overlay file.
  • When configuring individual authority records, you can now specify settings for the <terms-used> block in your museum's overlay file.
  • When configuring the vocabulary instances for your museum - the named vocabularies for persons, organizations, places, concepts, storage locations and more - that will hold authority terms, the contents of the <instances> configuration block in your museum's overlay file will now entirely replace the corresponding block in the default settings file, when the two files are merged. This gives you more control over these settings, making it easier to replace unwanted vocabularies from the default list with your own, as well as changing the ordering of vocabularies in dropdown menus.

Schema and configuration changes

Notes service has been deactivated (CSPACE-6189)

A "Notes" service has long been present in CollectionSpace, but was never exposed in the system's user interface, nor has it been used by other services, as was originally contemplated (see Annotation Service Notes). This service has been deactivated and is now deprecated.

Performance-related changes



Multiple bugfixes related to configuring CollectionSpace

While version 4.0 streamlines and simplifies the process of configuring CollectionSpace for your tenant (museum), multiple configuration-related bugs were fixed as well. These bugfixes should collectively result in making it easier and faster to make configuration changes and to test their impact on your system, as well as eliminating some potential sources of configuration errors:

Image loading no longer fails when the image repository hostname has not been configured (CSPACE-4051)

Loading of thumbnail and medium-sized image derivatives, on Media Handling and Cataloging record pages, for instance, no longer fails if the Internet hostname of the CollectionSpace system hasn't been configured in an <ims-url> configuration setting, and a user's web browser is accessing the system via its Internet hostname or IP address, rather than via a localhost URL.

(The default configurations for the demonstration core and lifesci tenants now include a hostname-free relative path for this setting, rather than a path that includes the localhost hostname, which appears to have been the cause of this issue. For standard CollectionSpace configurations where derivative images are loaded from local storage, this new configuration setting should "just work," regardless of the server's hostname or the host on which the user's browser is located.)

Application layer configuration files are now fully replaced during a build (CSPACE-6159)

A change to the build process for CollectionSpace's Application layer now ensures that any configuration files found in several locations within the Tomcat server folder are now replaced outright by (presumably more current) files being deployed from the Application layer source code tree. This is expected to make configuration changes and deployments more deterministic, in occasional cases where 'stale' files might not previously have been updated.

Application layer configuration files are no longer duplicated when deployed to the server (CSPACE-5980)

A change to the build process for CollectionSpace's Application layer now ensures that configuration files are copied (deployed) only to a single directory within the Tomcat server folder, where their settings can be viewed and (for ad hoc experimentation) edited. Previously, another set of those configuration files was redundantly bundled into a JAR file within a deployed WAR file, where their settings would override those in their user-visible counterparts, potentially leading to confusion where settings diverged between the two sets of files.

Results of Application layer configuration merges are now once again saved to disk (CSPACE-6193)

When adding fields or changing the behavior of existing fields, you can put just your museum's changed settings into an 'overlay' file, which is then merged with CollectionSpace's default settings. This makes it straightforward to identify "just what's changed" from the defaults, and eases the process of applying your changes when migrating your system to new CollectionSpace versions.

This bugfix restores your ability to physically view the results of these merges - of your changes contained in your museum's overlay files with their corresponding default settings - by saving them in a set of meaningfully-named files in Tomcat server's temp directory. That, in turn, makes it easier for you to incrementally debug and modify your overlay files to get things exactly how you want them.

Multiple bugfixes related to displaying object current locations

Several bugfixes collectively addressed some less common cases in which a field in the Cataloging record, which displays an object's current location, could contain an outdated or otherwise inaccurate value. (Note that the actual location of the object, maintained via related Location/Movement/Inventory records, was not affected by these bugs.)

Values of read-only fields can no longer be overridden by 'stale' values in the browser (CSPACE-6135)

Previously, values in read-only fields were sent from the browser to the CollectionSpace server, along with the values of writeable fields, when a record was saved. Now, as a result of this bugfix, values in read-only fields are never sent when saving records.

The previous behavior caused a problem when the values of read-only fields were 'stale' in a user's browser: in a state older than more recent updates made to the values of those fields via code running on the server (via event handlers, batch processes or the like). A save would then override the newer values with the older, 'stale' values. As one example, this behavior could sometimes result in out-of-date values for the Computed Current Location field in Cataloging records.

'Cloning' a Cataloging record via 'Create new from existing' no longer copies over Computed Current Location (CSPACE-6162)

Previously, when 'cloning' a Cataloging record by clicking the Create new from existing button, the value of the Computed Current Location field would be inappropriately copied over into the 'cloned' record. (Related Location/Inventory/Movement records aren't copied over to the cloned object, and thus no information is available regarding the cloned object's current location.) As a further source of confusion, this read-only value, while displayed initially on the screen for the newly-cloned record, would not be saved with that record, due to an earlier bugfix, CSPACE-6135.

Following this bugfix, the value of the Computed Current Location field is no longer copied over into the 'cloned' Cataloging record when you click Create new from existing.

Object current locations are kept up to date even when record versioning is enabled (CSPACE-6171)

In the event handler that keeps the value of the computedCurrentLocation field in Cataloging records updated with each object's probable current location, based on related Location/Movement/Inventory records, a bug was fixed that prevented these updates from occurring if record versioning was enabled.

(Versioning is a feature of Nuxeo EP, the enterprise content management system that underlies CollectionSpace, and can be selectively enabled for various record types via configuration.)

Importing into per-tenant repositories now works as expected (CSPACE-5950)

A bug was fixed that prevented importing records, via the Imports service, in scenarios where a museum's tenant has been configured to use a separate repository, thus storing its records in a separate database from those of other tenants on a CollectionSpace system.

Boolean fields can once again be emitted in list results (CSPACE-6114)

A bug was fixed that prevented Boolean fields from appearing in list results. This bug was introduced in the previous release, v3.3, as a side effect of a fix for CSPACE-5763.

Saving changes to existing, schema-extended Person or Organization records now succeeds without an error message (CSPACE-6158)

Previously, if you extended Person or Organization records to add your own fields, via an extension schema for your domain or museum, you might then encounter a generic "Error saving Person: error" or "Error saving Organization: error" message when attempting to edit and save changes to your existing Person or Organization records. (Your changes to those records would still be successfully saved; the error message was thus misleading.)

A previous workaround for this issue was described in CSPACE-4636: adding an additional configuration entry that declares your extension schema, to the Application layer's configuration file for Contact records, which are effectively a sub-record of both Persons and Organizations.

This bugfix eliminates both the spurious error messages and the need for this workaround.

Password reset emails are more reliably sent out (CSPACE-6221)

A bug was fixed that, under some circumstances, could prevent password reset emails from being sent. The bug was in a test that was performed prior to sending these email messages, and under some non-deterministic configurations for a museum (tenant), that test could erroneously fail.

Certain values are no longer truncated in title areas above records (CSPACE-6164)

A bug was fixed that had caused field values to be truncated by at least one character, when displayed in the title area above a record, if those values anywhere happened to contain the literal string urn (e.g. as in Burns or furniture). (The actual value of the field itself was not truncated; rather, the display of that value in large text above the record itself.)

System requirements changes



Note: there are significant compatibility issues with Internet Explorer 10, and possibly one or more older versions of IE, that remains to be addressed, as per CSPACE-6076. While first identified during version 3.3 testing, these issues may have been present in earlier releases.

Mozilla Firefox and Google Chrome remain supported Tier 1 browsers, and Safari (for Mac OS X) remains a supported Tier 2 browser.