Skip to end of metadata
Go to start of metadata

Documentation and installation

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

Save time when installing CollectionSpace


A new, automated installer for CollectionSpace 4.1 is now available for testing.  This can make installation considerably easier and faster! To try it out, please visit Automated installer for CollectionSpace 4.1.


CollectionSpace's version 4.1 release includes various feature enhancements and bugfixes, building on the previous release, 4.0. This release adds two new procedures: Condition Check and Valuation Control. The release has also focused on making significant improvements to stability and performance, as well as on support for hosting CollectionSpace in a Software as a Service (SaaS) model.

The major features of this release to date are:

  • Two new procedures: Condition Check and Valuation Control.
    • Condition Check: a procedure to manage information about the make-up and condition of an object, and recommendations for its use, treatment and surrounding environment.
      Valuation Control: a procedure to manage information relating to the financial valuations of individual objects and groups of objects, usually for insurance/indemnity purposes.
  • A large number of bugfixes, some addressing issues that were long present in CollectionSpace.  Bugs addressed included:
    • An intrusive usability issue affecting several specific pages, resulting from an inadvertently floating footer that prevented accessing data underneath, until the browser window was resized.
    • A major stability bug that could result in slowdowns or even require occasional server restarts, when running on large systems with many links between records.
    • At least eight different bugs that could result in various, often subtle forms of data corruption.  These bugs could have resulted in creation of duplicate records; inadvertent changes to metadata for some records; and missing applying changes to some records, when performing bulk updates to field values across multiple records, for example.
    • Several bugs that resulted in some type of data hiding.  These include reports not appearing in drop-down menus on certain record types.
  • Performance improvements, at least one of considerable significance for heavily used CollectionSpace systems, addressing a problem that might make such systems slow or unresponsive at times.
  • An automated installer, which can make it significantly easier and faster to install a CollectionSpace server.
  • Feature improvements of particular interest to those hosting CollectionSpace systems in a Software as a Service (SaaS) model, including:
    • Allowing multiple CollectionSpace systems to share a single database server.
    • Testing to provide assurance that CollectionSpace systems can use remote database servers, over a network, in a production environment.
  • Major improvements to wiki-based documentation, including:
    • Updates and additions that reflect the set of significant changes introduced in release 4.0.
    • The cleanup of most 'stub' (near-empty boilerplate), incomplete, and obsolete documents formerly present on the wiki.  (These cleaned-up documents no longer appear in links and sidebar navigation, but can still be accessed via search, at least for now.)

Release date and schedule

October 2, 2013: Development Begins
May 20, 2014: Tagging of CollectionSpace 4.1 beta 1 (tagged as "4.1-beta1"). This creates a stable, early release of CollectionSpace 4.1 that can be targeted by prospective implementers who are evaluating CollectionSpace, and by implementers who expect to go into production no earlier than January 2015.
May 20, 2014: Interim Code Freeze. For the CollectionSpace Services, Application, and UI source code repositories, only Blocker and Critical issues directly affecting implementations that are in production or under development will be considered for fixes, until the transition to LYRASIS (described below) begins.
May 29, 2014: Public Announcement. The 4.1 beta 1 release is publicly announced to the CollectionSpace community.
September 17, 2014: Beginning of the transition of the responsibility for CollectionSpace's core code (master branches) to LYRASIS, CollectionSpace's new organizational home, from project team developers at the University of California, Berkeley and at other CollectionSpace community partners. This began after LYRASIS staff were hired and became available for this work.
October 9, 2014: Development Ends
October 16, 2014: QA Testing Begins
November 11, 2014: QA Testing Ends
November 13, 2014: Release of CollectionSpace v4.1
December 15, 2014: Release of CollectionSpace v4.1.1, a minor set of bugfix patches applied to Release 4.1.

Release notes

Changes you'll need to make when upgrading to version 4.1

As a result of work on CSPACE-6168, making it possible for multiple CollectionSpace instances to share a single database server (see New functionality: Hosting and Software as a Service (SaaS) support, below, for more details), there were several minor changes made to CollectionSpace-related environment variables.  These variables are used when building CollectionSpace from source code, and when installing and running CollectionSpace servers.

If you will be upgrading an existing CollectionSpace system from version 4.0 or earlier, to version 4.1 or higher, please see Updating environment variables when upgrading to CollectionSpace 4.2, 4.3, or higher.  It should typically take ten minutes or less to manually make these changes to environment variables.

These changes are also reflected in installation documentation, as well as incorporated in the automated installer for CollectionSpace 4.1.  And if you haven't made one or more of the required changes, you'll be presented with specific error messages letting you know what you still need to change, each time that you run a Services layer build.

New functionality

New Condition Check procedure (CSPACE-6235)

A new Condition Check procedure has been added, to manage information about the make-up and condition of an object, and recommendations for its use, treatment and surrounding environment. The Condition Check procedure is a community contribution, contributed by Jesse Martinez, a CollectionSpace consultant to the Walker Art Center.

Depending on a museum's business practices, condition checks might be performed, for instance, when an object is subject to Intake, Loan In, and/or Acquisition; before and after the object undergoes conservation or other care; before and after an object is on exhibit or is in other use; and prior to Object Exit.

New Valuation Control procedure (CSPACE-6310)

A new Valuation Control procedure has been added, to manage information relating to the financial valuations of individual objects and groups of objects, usually for insurance/indemnity purposes.  The Valuation Control procedure is a community contribution, contributed by Jesse Martinez, a CollectionSpace consultant to the Walker Art Center.

Records can now be undeleted programmatically (CSPACE-6301)

Via one of CollectionSpace application programming interfaces, the Services Layer REST API , it is now possible to programmatically undelete records.

Technically, this involves making a request to transition a "soft deleted" record from its 'deleted' workflow state to an active (aka 'project') workflow state.  For more details, please see the relevant section of the Common Services REST API documentation. (In most instances in CollectionSpace, when you delete a record, you are simply "soft deleting" it by changing its workflow state; thus, those records can now be programmatically undeleted. A record that has been "hard deleted" - deleted via a HTTP DELETE request - cannot be undeleted via this or any other mechanism, however; it can only be restored from backup.)

Vocabulary terms can be initialized with descriptions (CSPACE-6420)

Via configuration files in the Application layer, it's now possible to provide initial descriptions for vocabulary terms that will be stored in the database, alongside those terms. These descriptions can then be seen and edited in the Administration -> Term List Management tab.

New functionality: Hosting and Software as a Service (SaaS) support

The following new functionality items are likely to be of particular interest to those hosting multiple CollectionSpace systems, including hosting based on a Software as a Service (SaaS) model:

Multiple CollectionSpace systems can now share a single database server (CSPACE-6168)

Prior to CollectionSpace version 4.1, each CollectionSpace system needed to have its own, associated (PostgreSQL) database server.  Two or more instances of CollectionSpace could not share a single database server, largely because multiple CollectionSpace systems might each attempt to use identical names for their associated databases and database user accounts ("roles"), and name collisions might result.

Version 4.1 introduced a feature that optionally allows any CollectionSpace system to be configured with an instance identifier: a string that is intended by convention to be unique to that instance of CollectionSpace.  If present, this identifier is added as a suffix, at creation time, to the names of all of its databases and database users.  This allows them to reside in a single database server alongside other databases and database users with comparably suffixed names, associated with other CollectionSpace systems.

To configure this instance identifier for your CollectionSpace system, edit the appropriate entry in the top-level file in the Services source code tree, as documented here.  You will need to make this change manually, prior to installation.  (There is also an outstanding issue, CSPACE-6390, to allow you to specify an instance identifier when using the automated installer for CollectionSpace servers.)

(This ability to share a single database server may be of particular interest to hosting providers, who host CollectionSpace instances as part of a Software as a Service (SaaS) offering.  For instance, multiple CollectionSpace instances, each holding small- to medium-sized collections, can now share a single, appropriately configured database server.  And in such a configuration, the hosts running CollectionSpace itself - potentially virtual machines or even lightweight containers - can often be more minimally configured, with less memory and disk space than would otherwise be required if each such host also needed to run a PostgreSQL database server instance.)

CollectionSpace's use of remote database servers was extensively tested and found to be production-ready (PAHMA-963)

A great deal of work related to remote database configuration and performance was carried out during the release 4.1 development period.  This resulted in a considerable degree of assurance that a CollectionSpace server can store its data in a remote PostgreSQL database server, even in a high capacity production environment. The work on this issue, which resulted in considerable experience being accumulated around remote database server configurations, included testing to ensure that network overhead did not significantly impair performance, and investigation and resolution of issues specific to the University of California, Berkeley data center environment.  (At least one of those issues, which pertained to failures of the very next connection attempted, following a timeout occurring in a networking software stack, firewall, or database server, is discussed in PAHMA-963.)

In version 4.1, this testing and investigative work is reflected in:

  • Easier configuration of CollectionSpace to use a remote database server.
  • Better error logging of network connectivity issues.

As well, a filter was added to CollectionSpace that retries connection attempts if network connectivity to remote resources is down or flaky.  While this filter is disabled in configuration by default, of this writing, it could potentially be activated, tested, and incorporated into a future CollectionSpace version.  (This filter wasn't needed to resolve the issues found during the testing described above, but is worthy of serious future consideration, for further improving CollectionSpace's robustness around network connectivity issues and remote resource failures.)

Overall, this work is expected to be particularly helpful to hosting providers who offer CollectionSpace in a Software as a Service (SaaS) model, as well as for museums and collections that would benefit by using a remote database server, perhaps one that includes professional database administration.

CollectionSpace's location for storing binary files is now configurable (CSPACE-6393)

Via an option in a configuration file, you can now specify where the Nuxeo enterprise content management system, which underlies CollectionSpace, stores binaries: such as image files, PDF files, and Office documents.

This makes it possible to store binaries in a mapped and/or linked external directory, rather than within the CollectionSpace server folder. This can facilitate cloud-obtained storage, and make it even more straightforward to host CollectionSpace servers in nearly interchangeable virtual machines or lightweight containers.

As well, this makes it possible for each museum or collection ("tenant") to be given a separate location in which to store its binaries, which makes it substantially easier to perform backups, data recovery, and metering of resource use by tenant, such as in a hosted environment.

Database connection options are now configurable (CSPACE-6404)

When setting up a connection between a CollectionSpace server and a database server, you can now configure JDBC connection options to match your specialized connection needs. For example, you can configure a CollectionSpace to use the TLS protocol to encrypt data that travels between the two servers.

Installation and maintenance tools

An automated installer for installing CollectionSpace server instances is now available (CSPACE-6170)

An automated installer allows you to install a CollectionSpace server on a Linux host by running a single command. The installer then carries out almost all of the steps you would have ordinarily needed to manually perform during an installation. (There are still a small number of completion steps you'll need to perform manually, after the installer finishes running.)

The installer is currently available for Debian- and RedHat-based Linux distributions.  To date, it's only been tested on a handful of distributions, however.  The CollectionSpace team welcomes you to try it out on your own Linux host or virtual machine; you're invited to help test by visiting Automated installer for CollectionSpace 4.1.

User interface improvements

Title bar now "docks" at top of record windows, remaining in place even when scrolling (CSPACE-6419)

By always displaying the record title and type near the top of the screen, even as you scroll through a record's fields, you no longer need to scroll all the way back to the top to confirm which record you're viewing. This feature is a community contribution, contributed by Ray Lee, a software developer in Research IT/Museum Informatics at the University of California, Berkeley.

Records now show creation and modification information (CSPACE-6423)

In an information block above each record, you can now see who created and last modified the record, and when they did so. This feature is a community contribution, contributed by Ray Lee, a software developer in Research IT/Museum Informatics at the University of California, Berkeley.

Instances of repeatable groups are better distinguished via alternating light and dark backgrounds (CSPACE-6136)

Multiple, onscreen blocks containing repeatable groups of fields are now more clearly distinguished from one another, by means of alternating light and dark backgrounds. This styling change is a community contribution, contributed by Amy Wieliczka, a software developer in Research IT/Museum Informatics at the University of California, Berkeley.

Existing template is retained after "cloning" a record via Create new from existing (CSPACE-6422)

When you "clone" the current record by clicking the "Create new from existing" button, the new record will be displayed in the same template as the original record. This feature is a community contribution, contributed by Ray Lee, a software developer in Research IT/Museum Informatics at the University of California, Berkeley.

Determination history block in Lifesci Cataloging records is far more usable (CSPACE-6174)

In Cataloging records in the sample Lifesci tenant, the fields of the repeatable Determination History block are now laid out across multiple lines, making it easier to view and edit the contents of each field.

Formerly, this block - which is used to associate scientific taxonomy terms with an object, along with information about the 'who, when, and why' of those taxonomic determinations - occupied a single line, and most of its fields were too small to be practically usable.

Several dimensions fields are ordered more logically (CSPACE-4638)

In Cataloging and Media records, several fields in the repeatable Dimensions block are now ordered more logically: the Measured By and Method (i.e. measurement method) fields are now adjacent, followed by the Value and Dimension Unit fields (and other value-related fields).

Reports now open in a new window or tab (CSPACE-6416)

Reports that are displayed in a browser window now open in a new window or tab, rather than taking over the window or tab from the record in which they were run.

Schema additions

None so far.

Performance-related changes

(Also see Bugfixes for additional changes that directly affect performance, particularly the fix to CSPACE-6286.)

Number of simultaneous Application layer connections to the Services layer has been significantly increased (CSPACE-6284)

A long-standing and significant performance-related bug was found and fixed, which limited CollectionSpace's Application layer to opening up no more than two simultaneous collections to CollectionSpace's Services layer (and hence, to the database). At times, this could result in blocking further actions by any user of the system, until at least one of the two existing requests completed. Long-running connections, such as those resulting from certain time-consuming searches, could trigger those blocking conditions.

By default, the Application layer can now open as many as 20 simultaneous connections to the Services layer. (This maximum value is also now configurable by changing a constant in Application layer source code and recompiling and redeploying that code, a process that can be completed within just a few minutes.)

Note: The changes in this fix, which were made to a single Java class file within the Application layer source code tree, can readily be applied by implementers to at least some earlier CollectionSpace releases, as well.

Returning lists of Media records is no longer slowed by a need to retrieve entire records (CSPACE-6241)

A configuration bug was fixed that inadvertently omitted blobCsid field values (identifiers for binary blobs) from being returned as a field in search results and other lists of Media records.

As a result of this omission, every record in the list had to be individually retrieved to obtain those values, thus degrading performance when returning lists of Media records.

Returning images and other binary files ("blobs") no longer requires opening those files to obtain their metadata (CSPACE-6111)

When a request is made to CollectionSpace's Services layer to retrieve an image or another type of binary file (PDF, Office-type document, etc.), that file's data is now returned directly.  Formerly, the file was opened and examined to extract its metadata, such as image dimensions, before its data was returned in the response.

This change speeds up the delivery of small images (such as "thumbnails"), in particular.  That, in turn, can help improve the performance of public portals and other external applications that interact with CollectionSpace's Services REST API to retrieve those images.

First-time installation and build process has been significantly sped up by caching more artifacts (CSPACE-6291)

First-time builds of CollectionSpace's Services layer have been made much faster. This resulted from two changes:

  • More comprehensive caching of Java library files and their related artifacts in the CollectionSpace project Maven repository.
  • Corresponding, minor modifications to configuration files (Maven POM files) in the Services layer source code, that direct the build to first look for cached artifacts in that repository, before going out to the Web to access artifacts in remote repositories.

First-time installations of a CollectionSpace server instance, as well as any other first-time builds of the Services layer by developers and implementers, typically should see a three- to four-fold speed improvement as a result of this change. (After a first-time build, these artifacts are typically cached in one's own local Maven repository, and so no further significant speedups will result.) This change also makes it feasible to complete an automated, unattended installation of a CollectionSpace server instance via a Puppet-based installer in approximately 30 minutes on a typical system, versus taking several hours (or more), prior to these caching-related changes.

Bugfixes (Release 4.1)


A fix for the bug described in CSPACE-6258 was targeted for Release 4.1, but didn't make it into that release; instead, it's scheduled to be included in a minor bugfix release, v4.1.1. You can also apply a patch to a v4.1 system to fix this bug; see CSPACE-6258 for details.

This bug causes non-preferred authority terms to not be displayed among the list of suggested terms below autocomplete fields, if, when you type text into those fields, you use wildcards or anchors in your query.

Footer no longer blocks access to page elements (CSPACE-6121)

A bug was fixed in which the footer at the bottom of selected CollectionSpace pages, including Create New, Administration and search results, formerly 'floated' over other page elements and blocked access to those elements directly below it: buttons and links, data entry fields, and the like. Getting access to those elements required resizing the browser window, each and every time this occurred.

This fix also resolves several other reported bugs, related to various user interface elements that were intermittently obscured by the floating footer.

Note: The salient change in this fix, which occurs in a single CSS stylesheet file, is to remove a CSS declaration that absolutely positioned the footer, although other cleanup work was done in that stylesheet as well. This change can readily be applied by implementers to earlier CollectionSpace releases, as well.

Resolution of slowdowns and out of memory conditions, where an authority term is referred to by large numbers of records (CSPACE-6286, CSPACE-6406)

A serious bug was fixed where, in instances where an authority term is referenced in one or more fields of a very large number of other records, building the display of a paginated list of those 'referring records' (also sometimes referred to as as 'object references') in the right sidebar could significantly slow or even halt system activity for a time. Under some circumstances, this could even result in an out of memory condition.

This bug occurred because, previously, data pertaining to all such referring records were retrieved at once. Now, these data are only retrieved in small, paginated batches, as needed, to populate the visible subset of references to those records that appear in the right sidebar.

Display name updates are now performed deterministically, no longer missing some update targets (CSPACE-6333)

A subtle data corruption bug was fixed, relating to automatic updates of display names.  Some background: when the display name for an authority term, or the display name for a record that can have hierarchical relationships (such as Cataloging records), is updated, that initiates a process within CollectionSpace that performs a bulk update to the references to that display name. Due to a bug in that process, however, those updates were not performed in a deterministic manner, and thus some references were missed, leaving the previous display name in place. This could result in, for instance, the visible name for Persons, Organizations, Concepts, or Storage Locations in certain Cataloging fields being left at a previous value, or the visible name for certain parent or child records within the Hierarchy section of Cataloging or authority term records similarly becoming out of date.

Now, when display names are now updated, the references to those names should also be uniformly updated, as well.  (This assertion is made, barring any timeout or other failure of the process that performs this update, in which case all changes within that transaction would be rolled back together to their previous state.)

Authority term records opened from search results now always appear in the correct vocabulary (CSPACE-6339)

Another subtle data corruption bug was fixed: when opening an authority term in a new browser tab or window, by right-clicking a link in a list of search results, CollectionSpace incorrectly determined that the term belonged to the default vocabulary for that type of authority term, even if the term, in fact, belonged to some other vocabulary. (There were some other circumstances, other than right-clicking, through which this behavior could also potentially occur.) If the record was subsequently saved, this could result in subtle corruption of CollectionSpace's internal metadata about that term record, which would in part result in the term visually appearing to have been moved into the default vocabulary.

This bug was fixed by ensuring that, in search results, every link to an authority term uniformly includes a parameter identifying that term's vocabulary name. Previously, that vocabulary name was added only by a Javascript "onclick handler," which could be bypassed by right-clicking the link, and which itself also contained some logic errors.

Add to Record from Advanced Search now more fully protects against creating duplicate relations between records (CSPACE-6363)

Floating decimal field values in the Place record are now validated (CSPACE-6323)

A quasi-data corruption bug was fixed, by now validating the values of several floating decimal fields in the Place authority term record on entry. Without that validation, it was possible to enter non-numeric text into those fields; when saving, they would revert to the value "0".

For a list of these fields, found within the Locality Information and Georeference Information sections of the Place record, see the description of CSPACE-6323.

Changing the case of display names now successfully updates refName display names in collectionspace_core (CSPACE-6372)

When changing just the case - not the text - of display names for certain record types, such as authority terms, the refName in the collectionspace_core schema that incorporates that display name was not being updated accordingly.

After fixing this bug, the refName in collectionspace_core now always reflects your display name case changes.  This ensures that your case changes will be reflected wherever the relevant values from collectionspace_core are displayed within CollectionSpace.

Multiple bugfixes related to authorities initialization

One of the mechanisms through which you populate your CollectionSpace system with data is known as "authorities initialization."  This process manages adding and updating values for:

  • A set of vocabularies (also known as "authorities"), which serve as containers for authority terms (controlled text) within specific topic areas.  In the demonstration Core and Lifesci tenants, for instance, authoritative terms for storage locations can be assigned to either of two vocabularies, which respectively contain terms pertaining to Local Storage Locations or Offsite Storage Locations, while terms for persons may be assigned to either a Local Persons or a ULAN Persons vocabulary.  By editing configuration files, you can change this set of vocabularies to meet the needs of your museum, by removing default vocabularies and adding your own vocabularies.
  • Vocabulary terms, which appear as options in many drop-down menus on CollectionSpace's record editing pages.  For instance, by default, several currency-related dropdown menus include vocabulary term options for the UK Pound, US Dollar, and Swiss Franc, along with various other currencies, while another drop-down menu in the Acquisition record offers "acquisition method" options of Gift, Purchase, Exchange and the like.  As above, by editing configuration files, you can change these lists of vocabulary terms to meet the needs of your museum, by removing default vocabulary terms and adding your own.

As described in the documentation on Initializing data, you can add or update this data by visiting an 'authorities initialization' URL, either when you first install CollectionSpace, or whenever you make changes to vocabularies and vocabulary term lists later on.  When a user with the appropriate access permissions makes a GET request to this URL, this triggers a request to CollectionSpace's Application layer to add or update authorities-related data, reading the current values from its configuration files and then writing that data to the database.

Three bugs in the authorities initialization process were identified and fixed in version 4.1.  The first two bugs were particularly significant, as they made it problematic to re-run this initialization process after a CollectionSpace system had been in operation for a time and various changes had been made to authorities and/or vocabulary terms.

Existing vocabulary terms are no longer duplicated or overwritten during authorities initialization (CSPACE-6302)

Prior to version 4.1, terms in the Application layer's configuration files were matched up with terms in the database on the basis of their display names.  This was problematic, since the display names of vocabulary terms are user-editable. Thus, performing an initialization after a CollectionSpace system had been in operation for a while, might inadvertently add one or more new, duplicate vocabulary terms, bearing the same internal identifiers as terms already in the database whose display names had been edited at some point.  Now, the task of matching up the terms in configuration files, with their counterpart terms stored in the database, always directly uses these unique, internal identifiers ("Short Identifiers"), which helps prevents duplication.

In addition, whenever data initialization was performed, existing, active terms in the database would always be overwritten by their matched terms from configuration files.  This effectively threw away any user-entered changes made to those terms in the database since the last initialization occurred, such as changes to their term status ("active" or "inactive") or edits made to many of the terms' other fields.  Now, existing terms are never overwritten by the initialization process.

Deleted vocabulary terms are no longer inadvertently re-created during authorities initialization (CSPACE-6371)

A bug was fixed that caused vocabulary terms that had previously been deleted to be re-created, during the authorities initialization process. This inadvertently ignored the (presumably) deliberate deletion of those terms by users. After this fix, a vocabulary term will not be created if an existing term bearing the same identifier is found, and that existing term is 'soft deleted' (in the 'deleted' workflow state).

This bugfix is complementary to work done via CSPACE-6302, described above; that issue fixed a bug that caused existing, non-deleted vocabulary terms to always be overwritten.

Vocabulary terms containing apostrophe characters can now be populated (CSPACE-6379)

A bug had prevented vocabulary terms, whose display names contained apostrophe characters, from being populated during authorities initialization. This bug is now fixed.

Formerly, such terms were skipped.  While this caused error messages to be generated during initialization, it is possible that someone might overlook those messages and not realize that these terms were not successfully imported.

Advanced searches no longer return the wrong types of records after switching away from vocabulary-specific authority item searches (CSPACE-6352)

In Advanced Search, a bug was fixed that resulted in the wrong types of records being returned in search results.  The bug could be triggered by conducting a search for authority terms, and choosing a specific vocabulary within that authority (rather than the default "All Vocabularies" search).  Then, without leaving Advanced Search, if you performed a second or subsequent search: on objects, on procedures, or on a different authority type, your second and subsequent searches would then continue returning the set of records that had been matched by the first search; that is, they would continue to return records from the formerly-selected authority and vocabulary.  (For instance, if you performed an Advanced Search on Person records and selected the "Local Persons" vocabulary, the search would return Person records in that vocabulary.  If you then performed an Advanced Search on Cataloging records, that search would continue to return Person records in the Local Persons vocabulary.)

After fixing this bug, you can now switch freely between Advanced Searches, and all such searches return the correct types of records in their search results.

Integer fields can be emitted in list results (CSPACE-6234)

A bug was fixed that prevented Integer fields from appearing in list results.

Non-preferred terms matched by a query now appear when the query contains wildcard or anchor characters (CSPACE-6258)


Reports are once again displayed in dropdown menus on four authority term record types (CSPACE-6288)

As a side effect of the Unified Configuration work in Release 4.0, reports were no longer appearing in the Run Report dropdown menu in the upper right sidebar, on record pages for four types of authority term records: Concept, Storage Location, Place, and Work. This bug was fixed, and now reports can once again be selected from the Run Report menus on those pages.

Page size dropdown menus in sidebar no longer contain duplicate values (CSPACE-6256)

In the right sidebar under Terms Used, Cataloging, or Procedures, the page size dropdown menu displayed the value 50 twice. This value now only appears once in that menu.

Imports no longer fail if an authority term refName contains a dollar sign (CSPACE-6277)

A bug was fixed that caused imports via the Imports Service to fail, if the import payload included an authority term (item) record with a refName value that included a dollar sign ('$') character.

Versioned records are now assigned major and minor version numbers (CSPACE-6334)

When record versioning was enabled for a particular record type (such as Location/Movement/Inventory records in the Lifesci tenant, where the versioning feature is demonstrated), major and minor version numbers weren't being assigned to versioned records. (Only a flag was assigned, which distinguished between versioned past copies of the record and the current copy.) This lack of version numbers could make it more challenging to write database queries, reports, or the like to compare successive versions of a versioned record.

This bug resulted from a missing schema reference in one or more configuration files. It was fixed by adding that missing schema reference to a prototype configuration file, from which those configuration files are generated. Following this change, when versioning is enabled for any relevant record type (e.g. for object records and/or any procedural records), major and minor version numbers will automatically be assigned to versioned past copies of records.

Updating a Media record to add or update its Blob (binary data) now uses PUT, not POST (CSPACE-6282)

Updating a Media record to add or update its Blob - that is, its associated binary data, such as an image file, PDF or Office document, etc. - now correctly uses an HTTP PUT request, rather than an HTTP POST request.

This change solely added the new PUT request to the Services REST API   for the Media service. To preserve backward compatibility, the existing POST request was left in place; it still works, but is now deprecated.

Returning small images and other binary files ("blobs") no longer takes up file descriptor resources (CSPACE-6110)

When a request is made to CollectionSpace's Services layer to retrieve small (256 KB or smaller) images or other binary files, CollectionSpace now returns these files' data via a method that doesn't require the use of file descriptor resources.  (File descriptors are "abstract indicators for accessing files" under Linux and other Unix-like operating systems; Microsoft Windows uses an equivalent concept, known as file handles.)

While strictly speaking, this change is not a bugfix, it can nonetheless help prevent the operating system from running out of available file descriptors, particularly if large numbers of small "thumbnail" images are being rapidly retrieved, by public portals or other external applications interacting with CollectionSpace's Services REST API .  When an operating system runs out of file descriptors, that will prevent users from logging into your CollectionSpace system, as well as impairing other CollectionSpace-related activities.   (Please note that you may also be able to configure your operating system to allocate a greater number of file descriptors, as described in the comments on CSPACE-6110, and thus help avoid running out of these resources.)

Colon characters in text labels are now always displayed (CSPACE-6208)

A bug was fixed that sometimes caused colon characters (":") in text labels to be suppressed. This bug resulted from an error when parsing key:value pairs in a configuration file, in CollectionSpace's User Interface layer.

Error messages when a required field is blank now are displayed correctly for date fields and option list fields (CSPACE-6276)

A bug was fixed that formerly caused error messages that warned of blank values in certain types of required fields - specifically date fields and option list fields (fields with a dropdown menu of choices) - to be displayed incorrectly. When displayed correctly, those messages would read Required field is empty: {fieldname}, where {fieldname} represents the name of the required field whose value was left blank. Due to this bug, however, those messages sometimes were rendered as [No messagecodes provided], and under other circumstances, the field names in the messages were displayed incorrectly.

Disambiguation values for Taxon terms are now appropriate (CSPACE-6421)

When you hover over a term in a dropdown menu below an autocomplete field, a disambiguation popup will appear. Formerly, when you hovered over a suggested Taxon term in the demonstration Lifesci tenant, this disambiguation popup displayed values inappropriate for Taxon: birth and death dates. (This likely resulted from configuration that was 'cloned' from Person terms.) Now, the popup displays values for three Taxon-pertinent fields: term status, term type, and taxon rank.

Useful error messages are now displayed when invalid values are entered into structured date fields on Work term records (CSPACE-6351)

A bug was fixed that returned garbled error messages when entering invalid text into structured date fields on Work term records.  These error messages formerly were similar to the following: [String for key: work-dateLatestMonthLabel is missing. ...]  Now, these error messages return useful information about which structured date fields contain invalid values.

Creating additional instances of two fields in Cataloging Advanced Search now works predictably (CSPACE-6431)

A bug was fixed that formerly could cause extra instances of either the Inscriber or Method fields to appear on the Cataloging Advanced Search page, when you clicked the '+' ( plus / add ) button above either field.  Now, those two fields are combined in a Non-Textual Description repeatable group, and creating additional instances of that group behaves predictably.

Bugfixes (Release 4.1.1)

The following bugs are fixed in Release 4.1.1, a minor set of bugfix patches applied to Release 4.1:

Instance-qualified CollectionSpace installations are working once again (CSPACE-6504)

In CollectionSpace Release 4.1, a significant feature was added, via CSPACE-6168, that allowed multiple CollectionSpace servers to store their data in a single database server. This feature, especially valuable for organizations hosting multiple CollectionSpace servers, allows the names of databases and database users to be "instance-qualified" so that they can be given unique names in the database server, thus avoiding naming conflicts.

Due to a regression bug introduced late in Release 4.1, this feature was "broken." If you added a unique identifier to your CollectionSpace server instance - to distinguish it from other servers sharing the same database - and then installed your CollectionSpace server, the installation would fail during the ant import process, during which default roles and permissions are imported. This bug has since been fixed in Release 4.1.1.

Non-preferred terms matched by a query now appear when the query contains wildcard or anchor characters (CSPACE-6258)

Reports are now run using read-only connections (CSPACE-6523)

A potential security vulnerability was addressed by now running reports using read-only connections to the database, when these reports are initiated via the Run button next to CollectionSpace's Run report menu. Previously, reports that were run in this manner used read-write connections to the database, which thus granted more extensive privileges than were required for this task.

This change also ensures that automated tests of reporting functionality use the same privileges for their database connections that are used in the 'real world,' when remotely running reports against the database.

The default 'reader' database user has once again been granted the privileges needed to remotely run reports (CSPACE-6520)

A regression bug introduced during Release 4.1 has been fixed. This bug prevented the default reader database user from being granted the read access (SELECT privileges) needed for remotely running reports against the database. This bug thus blocked the ability to run reports remotely, via psql and other, similar client applications and scripts capable of connecting to PostgreSQL, when authenticating as that reader database user.

Sample Acquisition Summary report is working once again (CSPACE-6511)

A bug was fixed that prevented running the sample Acquisition Summary report that ships with CollectionSpace.

After a redesign of the CollectionSpace website, one week following the CollectionSpace v4.1 release, running these sample reports resulted in an Error creating report:error message in the Message Bar. The underlying error was a failure to retrieve an image file of the CollectionSpace logo from that website; this bug was resolved by restoring access to that file and updating the relevant image URL in the report itself.

Build-related changes

Nuxeo config files for tenant-specific repositories are now created automatically (CSPACE-6329)

Functionality was added in version 4.1 that, during each system startup, automatically creates the configuration files required by Nuxeo for each per-tenant repository, based on values read from CollectionSpace's tenant configuration files.

Background: In CollectionSpace version 3.2, the ability to create tenant-specific repositories was offered for the first time, via work on CSPACE-4979.  That meant that, by making one simple change from the default settings, your museum's or collection's "tenant" (workspace) in CollectionSpace could store nearly all of its records in its own database, rather than sharing the default database with all other tenants.  This, in turn, makes it easier to separately back up just your own tenant's data, and makes it simpler to write reports against that data.

However, to make this change fully work, it was also necessary to create a brand new configuration file, containing details about your new, per-tenant repository, for use by Nuxeo, the enterprise content management system that underlies CollectionSpace.  (And this requirement was largely undocumented, as well.)

Formerly, you needed to know about this requirement, create this Nuxeo configuration file manually, and place it in the correct location within the CollectionSpace server folder.  Now, this file is generated in the correct location automatically.  And because this generation process takes place during each system startup, configuration files for additional tenants with per-tenant repositories that you might add in the future can automatically be created when needed, as well.

Additional protections are offered from inadvertent data loss when running development-related commands (CSPACE-6322)

When running a particular Ant command oriented toward CollectionSpace developers, it is now more difficult to inadvertently delete data: you must now confirm that you wish to run that command in a destructive manner by adding a parameter to that command.

Because this command is also run during first-time installations, this new parameter is documented in the 4.1 Installation Guides.

nightly-settings.xml file was removed (CSPACE-6175)

The nightly-settings.xml file was removed from the build. This Application-layer settings file was an artifact of past build practices, and its presence occasionally caused confusion.

Behavior changes

There are two user-visible behavior changes in release 4.1 pertaining to maintaining the value of the computed current location field in the Cataloging record, which displays an object's current location.

Computed current locations in Cataloging records can no longer be set to blank locations (CSPACE-6308)

The event handler that detects changes in Location/Movement/Inventory records related to Cataloging (object) records, and updates the value of the computed current locations in the latter, will no longer 'blank out' the current location for the Cataloging record, even if the most recent L/M/I record itself has a blank location value. The last known location for the Cataloging record will be retained within that record.

(You can indicate that an object's location is unknown, or in some other status not specific to any location, by first setting up special Storage Location terms for those status conditions and then setting the value of an L/M/I record's current location field to one of those terms.)

The most recent Movement (L/M/I) record is now identified by its modification date, not its creation date, for tiebreaking purposes (CSPACE-6307)

If a Cataloging record is related to two or more Location/Movement/Inventory (L/M/I) records that all bear the same date, for the most recent move(s) and/or inventory event(s), the event handler that updates the Cataloging record's computed current location will now choose the most recent related L/M/I record based on its updatedAt (modification date) value, rather than on its createdAt (creation date) value.

The batch job that you can run manually to update a Cataloging record's computed current location also now uses the same tiebreaker logic, per CSPACE-6129. Formerly, this batch job did not use a tiebreaker.

Vocabulary terms can now be loaded into fields in extension schema, for sub-records like Contacts and Dimensions (CSPACE-6417)

A bug was fixed that affected the behavior of one type of per-museum customizations to sub-records such as Contacts (a sub-record of Persons and Organizations), and Dimensions (a sub-record of Cataloging and Media Handling).

Specifically, when extending CollectionSpace's sub-records like Contacts or Dimensions to add custom schemas to meet the needs of particular museums, this bug prevented fields in those schemas that were linked to database-stored vocabularies from being automatically populated with terms from those vocabularies. As an example, if you created an extension schema to customize Contacts, which added a Country field that obtained its vocabulary terms from the database, the expected list of country names would not appear in that field's dropdown menu.

Documentation changes

Wiki documentation has been updated and significantly cleaned up (CSPACE-6252)

The wiki-based documentation for implementers was updated, in large part to reflect the many changes introduced in version 4.0.  Documents were updated throughout the wiki, particularly in the Configuring CollectionSpace section, in part to reflect the Unified Configuration changes introduced in that release, and new documents were added where appropriate.

As well, as part of this work, the wiki-based documentation was significantly cleaned up and reorganized.  Large numbers of 'stub' (nearly empty boilerplate), incomplete, and obsolete documents were identified and cleared away, by being moved outside of the documentation wiki's table of contents.  (These documents no longer appear in links on landing pages, or in the navigational links in the left sidebar, but as of this writing can still be retrieved via search.)  New top-level sections were created, along with new sub-topics within both new and existing sections.  And as well, summary and introductory text was added or rewritten throughout the wiki.

User interface JavaScript API documentation has been added

Additional documentation has been added for the JavaScript API in CollectionSpace's User Interface (UI) layer, which directly or indirectly pertains to configuration, customization, and software development in that layer. This highly technical documentation is aimed at CollectionSpace project and community developers, and at CollectionSpace implementers who wish to modify or extend UI behavior.

System requirements changes

None so far.


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.