Skip to end of metadata
Go to start of metadata

Documentation and installation

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

Overview

CollectionSpace's version 3.2.1 release includes various feature enhancements and bugfixes, building on the previous major release, 3.2. These changes were made by software developers at UC Berkeley as contributions to CollectionSpace.

Some of the key changes in this release include:

  • Reporting improvements, including the ability to generate reports in seven new formats, in addition to PDF.
  • Performance improvements.
  • The ability to much more easily generate a default set of users, roles, and access permissions for newly-added tenants.

Release date and schedule

CollectionSpace version 3.2.1 was released on February 27, 2013.

Through February 15, 2013: Development
February 19-27, 2013: QA and Release

Release notes

New functionality

Multiple reporting improvements, including multiple report formats (Excel, CSV ...), passing parameters (CSPACE-5305)

Reporting functionality improvements include:

  • Reports can now be generated in multiple formats - Word, Excel, PowerPoint, HTML, XML, CSV (comma-separated value) and TSV (tab-separated value) - in addition to PDF. This is specified in the outputMIME element when creating the report (unfortunately, currently only possible with cURL or some equivalent).
    • For MS Word (open docx), use "application/msword" or "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    • For MS Excel (open xlsx), use "application/vnd.ms-excel" or "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
    • For MS PowerPoint (open pptx), use "application/vnd.ms-powerpoint" or "application/vnd.openxmlformats-officedocument.presentationml.presentation"
    • For HTML, use "text/html"
    • For XML, use "application/xml"
    • For CSV, use "text/csv"
    • For TSV, use "text/tab-separated-values"
    • For PDF, use "application/pdf"
  • Parameters can be passed into canned reports; a provided example will generate a report based on a supplied calendar year value. (This 'passing parameters' functionality is available to report invocations via curl, etc., but is not yet available in the UI). If you look at the sample report in the source, acq_basic.jrxml, you will see a parameter "queryYear" that provides an example of how such a parameter is defined and used in the report. Here is an example invocationContext payload that passes the parameter:

Automatic updating of reports using new JasperReports versions (CSPACE-4876)

When you are copying your JasperReports report files into place so they can be run within CollectionSpace (e.g. to $CSPACE_JEESERVER_HOME/cspace/reports on Linux/Mac OS X/Unix-like systems or %CSPACE_JEESERVER_HOME%\cspace\reports on Windows systems), you can now copy your .jrxml XML source files instead of your compiled .jasper files. Each of your reports will then be automatically compiled 'on the fly' to .jasper files, the first time they are run.

When CollectionSpace upgrades to a new version of JasperReports, you can just delete your existing .jasper files when you upgrade, and your reports will be automatically recompiled using that new version, the first time they are run.

A new PublicItem service, making it possible to publicly share items in a CollectionSpace system (CSPACE-5833)

A newly-added service, PublicItem, makes it feasible to "publish" selected items in a CollectionSpace system, allowing them to be publicly shared with others who do not have a user account within that system.

This service was initially developed to integrate with the Berkeley Mapper system, to allow you to plot the relevant locations of selected items in a CollectionSpace system on a map, such as the field collection locations of selected objects. (The Berkeley Mapper system requires unauthenticated access to delimited text files that contain the data to be mapped.)

However, the PublicItem service also provides a general purpose mechanism for making selected items available for unauthenticated, public access. Initially, this service is configured to work with the output of reports, so that you can share your generated report output, but it can also be configured to "publish" and publicly share digital media, for instance.

Some background information related to this service:

Enhancements to application of access permissions (CSPACE-5741) and (CSPACE-5815)

Changes have been made to the way that access permissions are applied. These changes make it more flexible and easier to add:

  • Tenants, allowing you to easily add roles, permissions, etc. for a new tenant. (CSPACE-5741)
  • Extension procedures that supplement CollectionSpace's "out of the box" set of procedures, allowing you to easily add permissions for those new procedures. (CSPACE-5815)

This work is concisely summarized in this post to the project's Work list.

Script for migrating users and roles from older systems (CSPACE-5862)

Building on the more flexible access permissions changes described above, a SQL script is now available to update the authentication and authorization databases from older CollectionSpace systems, so that customized sets of users, roles and role-associated permissions in those older systems can readily be migrated to systems based on newer CollectionSpace releases, version 3.2.1 and higher. This script, with instructions, can be found here:

https://github.com/collectionspace/Tools/blob/master/scripts/clear_role_0_admin.sql

And some general background on this process can also be found here:

Migrating existing users and roles to a new CollectionSpace system

Creating initially-disabled tenants (CSPACE-5771)

New tenants can be created in an initially-disabled mode. This minimizes resources devoted to the tenant, which will remain disabled until its relevant configuration setting is altered and the system is restarted.

See this discussion thread on the project's Talk list for details.

Batch job to update computed current location (CSPACE-5728)

A batch job is available to set the value of the computedCurrentLocation field in specified Cataloging records with each object's probable current location, based on its related Location/Movement/Inventory records. The batch job can be invoked to update a single CollectionObject record; a list of records, specified by their CSIDs; the CollectionObject records related to a Group record; or all active CollectionObject records in the system.

Batch jobs like these can be run via curl, etc., but are not yet invocable via CollectionSpace's user interface; that is, pending the contribution and integration of Ray Lee's work on this functionality for a UC Berkeley implementation, UCJEPS-322, into CollectionSpace's master branch.

This batch job supplements an event listener, previously added in version 3.2, that helps keep the value of that field dynamically updated.

Enhanced ability to run custom SQL scripts at startup (CSPACE-5813)

Multiple, custom SQL scripts can be associated with a particular service (and hence, a particular record type), and configured to be run at every system startup.

This can be useful if the presence of custom database behavior (e.g. SQL functions, triggers, specialized types of indexes) needs to be checked for at each startup, and added to the database if not already present.

The ability to run one custom SQL script per service, during startup, had already been added in version 3.2; this is a minor change allowing multiple custom scripts to be run for each service.

Schema additions

New 'formatted display name' field in authority terms (CSPACE-5818)

A termFormattedDisplayName field has been added - to date, in the Services layer only - to the repeatable term information group of every authority term record.

This optional field can be used for storage of formatted display names using a museum's choice of markup/styling (expected to typically be HTML markup). For instance, one museum plans to style parts of scientific taxonomy terms in italics using this field.

Note that, while this addition means you can now store data in this field via data import or REST API calls, to use it fully from within CollectionSpace's user interface, you'll also need to add this field to the relevant Application layer configuration file(s) and UI layer HTML template file(s).

Ray Lee provided the following additional information about how to make use of HTML markup stored in this field:

  • In iReports, you have to configure the field specially to be rendered as formatted text:
    http://jasperreports.sourceforge.net/sample.reference/markup/index.html
  • For use in external webapps, HTML templating languages generally have some way of specifying that a string contains HTML that should be rendered.
  • In JavaScript applications, you'd set innerHTML instead of innerText/textContent.

Reporting software update to JasperReports 5.0.1 (CSPACE-4876)

The version of the JasperReports reporting engine used by CollectionSpace has been updated to version 5.0.1. This replaces the previously-installed version, 4.5.1.

Existing reports should continue to work as before, following this update. This change should also allow report writers to use more recent versions of iReport, Jaspersoft's report designer tool.

Performance-related changes

Clicking authority term links retrieved in search results no longer results in costly searches (CSPACE-5867)

A bug has been fixed that inadvertently resulted in searches to retrieve all authority term records of a specific type, when a user simply clicked a single authority term's link in search results. This particularly degraded system performance on large systems, containing tens or hundreds of thousands of authority term records of a particular type.

The work on this bug also resulted in new functionality, permitting the retrieval of related media records for authority terms, such as digital images associated with a person or organization term, for instance. (As of this release, those media records would need to be related to authority terms via programmatic means, by creating new relation records between terms and media, as there isn't yet a way to associate media with an authority term via CollectionSpace's user interface.)

Page loading of authority terms used by large numbers of records is now significantly faster (CSPACE-5870)

A bug that made it slow to load an authority term (item) record, when that term was widely used in many other records (had many "referencing objects") has been fixed. This bug was particularly noticeable when a term was used by hundreds or thousands of other records.

In work on this bug, it was also identified that counts of the uses of a term in related objects are underestimated, possibly as a result of instances where a term may be used in multiple fields within individual documents. There may be future UI label tweaks to better convey this to users. See this comment for details.

Optional speedup of autocomplete behavior (CSPACE-5740)

You can now optionally disable the behavior that adds a starting wildcard when doing partial term matching. (These are the searches that return a set of suggested choices, based on text you type into autocomplete fields.) This optional change offers the potential to significantly speed up such searches, particularly in large datasets, at the expense of having to manually add a leading wildcard character if you wish to restore the previous matching behavior.

(The current default behavior is unchanged; there is a commented-out section in the lifesci tenant's configuration that shows how to enable this new, optional behavior for any particular tenant.)

Reduced logging to disk (CSPACE-5775)

CollectionSpace's Services and Application layers were formerly configured to write messages to log files on disk at a highly verbose level. This likely resulted in at least some modest negative impact on performance.

Changes made to CollectionSpace's default logging configuration via this issue and companion issues CSPACE-5839, CSPACE-5840, and CSPACE-5841 should reduce the verbosity of this logging by an estimated 70% to 85%. In addition, these changes entirely disable the Application layer's logging to a performance monitoring-specific log file. (You can temporarily restore more verbose logging whenever it may be needed by making simple - frequently just one-line - changes to logging configuration.)

Ensuring that an 'asterisk-only' advanced search doesn't impair performance (CSPACE-5828)

Advanced searches consisting of a single asterisk in a field no longer initiate expensive queries that can significantly impair system performance, particularly on systems with large numbers of records.

Bugfixes

Sorting by fields in extension schemas now works properly (CSPACE-5844)

A bug affecting implementers where changing the sortBy field to any field in an extension schema resulted in an error has been fixed.

Running reports no longer can result in losing unsaved changes in some scenarios (CSPACE-5891)

In some browsers, a user could potentially lose unsaved changes to a record, if they ran a report with a generated output format (such as PDF) that might be displayed directly within a browser tab or window. This could cause the user to be redirected away from the record editing page, and their changes might be lost upon returning to that page.

The dialog that appears under these circumstances now prevents data loss by requiring the user to either save changes before running the report, or to cancel running the report and return to their record.

Preventing 're-parenting' of child records in a hierarchy when 'cloning' a parent record (CSPACE-5904)

A bug was fixed that could result in a child record (such as a Cataloging object's sub-component, or an authority term used in a narrower context) being assigned without warning to a newly-added parent record in a hierarchy, when its parent record was 'cloned' via the Create New From Existing button.

Ensuring that media uploads are successful even where filenames contain special characters (CSPACE-5497)

A bug was fixed where media uploads whose original filenames contained an equal sign ('='), comma (','), or certain other special characters would fail.

Following this fix, media files are stored on the server with underscores ('_') replacing these special characters, but the original, as-uploaded filename is still retained in metadata.

Workaround for a Maven 3 bug on certain platforms (CSPACE-3431 and CSPACE-4711)

A minor workaround is now in place for an issue when using Maven 3 to build and deploy the CollectionSpace Services layer on Mac OS X and at least some Linux distributions. This error, apparently in Ant's hand-off of a specific parameter when executing Maven, resulted in an Unknown lifecycle phase error. The workaround allows you to use Maven 3, the most up-to-date release of this build tool, to build and deploy the CollectionSpace Services layer on all platforms; as a result, Maven 3 is now the recommended version of this build tool.

System requirements changes

Java 7 is required, due to discontinuation of security patches for Java 6

Oracle Corporation recommends that users migrate to Java 7 (JDK 7) "in order to continue receiving public updates and security enhancements." Oracle stated that it will not be issuing any more updates - including security updates - for Java 6.

As a result, CollectionSpace 3.2.1 now requires Java 7 (CSPACE-5842), and installation documents have been updated with Java 7-specific instructions (CSPACE-5873).

There is also documentation on how to transition an older CollectionSpace system from using Java 6 to using Java 7 (CSPACE-5848).

Maven 3 is now highly recommended

Apache Maven is an open source development tool that is central to building and deploying CollectionSpace's software. Maven 3.0.x is the latest release of this tool, offering many - largely internal - improvements, and is now the recommended, standard version of Maven for use with CollectionSpace.

Users of Maven 2.x are strongly encouraged to install and start using Maven 3. Maven 3 is highly compatible with POM files and other artifacts created for use with Maven 2 and thus, following that transition, most users will see no appreciable differences, other than slightly different console messages when running Maven. Going forward, CollectionSpace will be developed only with Maven 3 and later versions, and thus any issues you may encounter specific to Maven 2 will be best resolvable by upgrading to Maven 3 or later.

Existing documentation has been updated (CSPACE-5853) to reflect this transition.