Content Comparison

...

Preparing reports for running from within CollectionSpace

To make the report available to CollectionSpace:

1. Copy the .jrxml file to the reports directory on the server. Report files should be installed in the cspace/reports directory under the Tomcat directory (whose path should be in the CSPACE_JEESERVER_HOME environment variable). Note the name of the file, e.g., "acq_basic.jrxml".

...

Report description XML record

For each report created, best practice is to create an XML record that has the same name as the report .jrxml file, and which lives in the same place. For instance, if you create acq_basic.jrxml, also create acq_basic.xml.

The XML record is used to add the report to CollectionSpace, and sets report properties and behaviors. An example report XML file is shown below.

The rest of this section details the meaning/use of the XML record elements.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document name="report">
  <ns2:reports_common xmlns:ns2="http://collectionspace.org/services/report">
    <name>Sample Acquisition Report</name>
    <notes>This<notes>Reports ison aobjects sample related to a given Acquisition report.<record</notes>
    <forDocTypes>
      <forDocType>Acquisition</forDocType>
    </forDocTypes>
    <supportsSingleDoc>true</supportsSingleDoc>
    <supportsDocList>false</supportsDocList>
    <supportsGroup>false</supportsGroup>
    <supportsNoContext>true</supportsNoContext>
    <filename>acq_basic.jrxml</filename>
    <outputMIME>application/pdf</outputMIME>
  </ns2:reports_common>
</document>

Your admin can use the following command to create the report record in CollectionSpace. Replace "{yourtenant}" with the name of your tenant, and replace "{password}" with your admin password. This assumes you have saved the XML file above as "report.xml":

curl -X POST http://localhost:8180/cspace-services/reports
  -i -u admin@{yourtenant}.collectionspace.org:{password}
  -H "Content-Type: application/xml" -T report.xml

Installing reports automatically

As of release 7.2, CollectionSpace automatically installs built-in reports on startup, so creating report records manually using curl is not necessary. To make a report automatically install:

1. Add the .jrxml file to the built-in reports directory in the services source tree on your server. This directory is located at services/report/3rdparty/jasper-cs-report/src/main/resources inside the services source code directory.

2. Add a report metadata record .xml file to the same directory. This file must have the same name as the report file, but the extension .xml instead of .jrxml.

3. Add the report to the tenant bindings file for your tenant. This file is located at services/common/src/main/cspace/config/services/tenants/{yourtenant}/{yourtenant}-tenant-bindings.delta.xml inside the services source code directory. Replace "{yourtenant}" with the name of your tenant. The tenant binding file for the publicart tenant contains an example of what to add: https://github.com/collectionspace/services/blob/676faa9cf37ee4d99816d3392eb1984d247cfb0b/services/common/src/main/cspace/config/services/tenants/publicart/publicart-tenant-bindings.delta.xml#L11-L22. For each report you want to have installed automatically, create property with the key "report", and set the value to the name of the report (the name of the .jrxml and .xml files, without the extension).

4. Redeploy the services, and restart CollectionSpace. The report should appear in the CollectionSpace UI.

Documents and forDocType values

...

name element

The name of the report as displayed in CollectionSpace UI

notes element

Description of report shown for report in CollectionSpace UI

forDocTypes / forDocType element grouping

Controls the record type(s) in which the user will see the report in the UI. This may or may not match the record type(s) contained in the resulting report.

The above report will be available from inside an Acquisition record. The unique system id of the record from which the report is invoked will be passed to the report in the csid parameter. The report returns information about Objects because the report query selects Objects related to the given Acquisition.

The forDocType element is repeatable, so the above report could easily be generalized to a “Related Objects” report runnable from any procedure record type listed in forDocTypes.

Where to find the correct docType values

Registered docType values will be categorized into service groups, available via the /servicegroups REST-ful API service for the given CollectionSpace instance.

Examples for the Anthro sandbox site:

• https://anthro.collectionspace.org/cspace-services/servicegroups/procedure

• https://anthro.collectionspace.org/cspace-services/servicegroups/authority

The docType value for Objects is CollectionObject (Check /servicegroups/object for your instance to verify.)

supportsSingleDoc element

If true, the report will be available to run from inside any record type listed in forDocTypes. The above report will be available from inside an Acquisition record. The unique system id of the record from which the report is invoked will be passed to the report in the csid parameter.

If false, the report will not be available when viewing an individual record.

supportsDocList element

If true, the report will be available on single-record-type lists of the record types specified in forDocTypes. The user must select one or more records in the list in order to run the report.

If false, the report is not available in such record lists.

The unique ids of the selected records are passed to the report in the csidlist parameter.

<forDocTypes>
  <forDocType>CollectionObject</forDocType>
</forDocTypes>
<supportsSingleDoc>false</supportsSingleDoc>
<supportsDocList>true</supportsDocList>

The above would cause the report to be available from:

1. Search results where the search was limited to Objects

2. The “Objects related to {record number}” page available from any procedure record

This report would not be available from the following because these are lists of mixed record types:

1. A search scoped to “All Records”

2. The “Uses of {term}” page available for authority terms

supportsNoContext element

If true, the report is runnable from Tools > Reports without requiring the user to select any records. The report runs across the entire database. No csid, csidlist, or groupcsid parameter values are passed to the report. The report’s whereclause should handle selecting all records meeting the desired criteria.

If false, the report cannot be run on the entire database.

Note that, if supportsNoContext is true and the other supports elements are false, the forDocTypes values are irrelevant. You could specify forDocType = Uoc, but if the whereclause parameter in the report is written to select object data, the report is returning object data! It won’t be shown in any records or on any record lists.

TODO: Test whether forDocTypes can be omitted for such reports

supportsGroup element

Only one of the 41 reports that ship with CollectionSpace right now have this one set to true. Here is the relevant part of its .xml:

<forDocTypes>
  <forDocType>CollectionObject</forDocType>
</forDocTypes>
<supportsSingleDoc>true</supportsSingleDoc>
<supportsDocList>true</supportsDocList>
<supportsGroup>true</supportsGroup>
<supportsNoContext>false</supportsNoContext>

This means you can run the report from:

• within a given Object record

• a list of Object records

• within a Group record

Running the report from a Group record passes the csid of the Group to the report as the groupcsid parameter.

Note that a Group may “contain” (i.e. be related to) Objects, other Groups, or any other procedural record types. Different types of records can be in a group together.

The reporting logic does not check whether a Group contains the target record type(s) when determining whether to display the report as runnable on the Group. If you have a group that consists of Loan In and Loan Out procedures, the above report will be runnable from the Group. The resulting report contain no records.

For reports with supportsGroup = true, the whereclause in the report must appropriately select records of the desired types from all the records related to the Group. In the above report, the whereclause is complex, providing selection logic for (1) a single Object; (2) a list of Objects; and (3) all the Objects related to a given group.

With supportsGroup = false, this report could still be run on all the Group’s Related Objects, with some extra clicking. However, if there are over ~200 related Objects, users might receive an error due to the issue linked in the supportsDocList section.

Until that issue has been resolved, you might consider implementing supportsGroup = true as a workaround. If a user needed to generate a report on 500 Objects, they could create a temporary Group, relate the 500 Objects to the Group, and then run the report on the Group. Since only the Group’s csid is sent to the report as a parameter,

filename element

The .jrxml filename. Ideally the XML file containing the report description should be exactly the same, but with “.xml” instead of “.jrxml” file extension.

outputMIME element

When this element appears as a child of the ns2:reports_common element, it sets the default output format for the report. The default output format is preselected when a user invokes the report. All supported report formats are available for selection.

Note that you can also do this:

<ns2:reports_common xmlns:ns2="http://collectionspace.org/services/report">
 [...]
  <supportsOutputMIMEList>
    <outputMIME>text/csv</outputMIME>
  </supportsOutputMIMEList>
  <outputMIME>text/csv</outputMIME>
</ns2:reports_common>

supportsOutputMIMEList allows you to constrain the output formats available to selection to the ones you specify. Multiple outputMime elements can be nested inside this element.

The top-level, non-nested outputMIME element sets CSV as the default output format.

The list of currently-supported report output MIME types can be found in the default reportMimeTypes option list configuration.

The above config looks redundant: why specify a preferred output format when there is only one output format? Indeed, the report can be run without specifying the default output format. However, the non-nested/top-level outputMIME value is used to populate the Default output format in the Tools > Reports screen, so it is best to provide this information.

...

Preparing reports for running from within CollectionSpace

To make the report available to CollectionSpace:

1. Copy the .jrxml file to the reports directory on the server. Report files should be installed in the cspace/reports directory under the Tomcat directory (whose path should be in the CSPACE_JEESERVER_HOME environment variable). Note the name of the file, e.g., "acq_basic.jrxml".

2. CollectionSpace admins and any other users with Utility Resources > Reports > Write permission can use the following command to create the report record in CollectionSpace:

   1. Replace http://localhost:8180 with the base url of your CollectionSpace instance.

   2. Replace {username} with your CollectionSpace user name and {password} with your password.

   3. This assumes you have saved the XML file discussed above as "acq_basic.xml" and are running the command from the directory containing the file.

curl -X POST http://localhost:8180/cspace-services/reports
  -i -u {username}:{password}
  -H "Content-Type: application/xml" -T acq_basic.xml

Installing reports automatically

As of release 7.2, CollectionSpace automatically installs built-in reports on startup, so creating report records manually using curl is not necessary. To make a report automatically install:

1. Add the .jrxml file to the built-in reports directory in the services source tree on your server. This directory is located at services/report/3rdparty/jasper-cs-report/src/main/resources inside the services source code directory.

2. Add a report metadata record .xml file to the same directory. This file must have the same name as the report file, but the extension .xml instead of .jrxml.

3. Add the report to the tenant bindings file for your tenant. This file is located at services/common/src/main/cspace/config/services/tenants/{yourtenant}/{yourtenant}-tenant-bindings.delta.xml inside the services source code directory. Replace "{yourtenant}" with the name of your tenant. The tenant binding file for the publicart tenant contains an example of what to add: https://github.com/collectionspace/services/blob/676faa9cf37ee4d99816d3392eb1984d247cfb0b/services/common/src/main/cspace/config/services/tenants/publicart/publicart-tenant-bindings.delta.xml#L11-L22. For each report you want to have installed automatically, create property with the key "report", and set the value to the name of the report (the name of the .jrxml and .xml files, without the extension).

4. Redeploy the services, and restart CollectionSpace. The report should appear in the CollectionSpace UI.

Running a report

You can run (invoke, or generate) a report:

...