Content Comparison

Prerequisites

To author reports, you need to have:

• Downloaded and installed the Jaspersoft Studio application

• Obtained a basic familiarity with using this application.

• Set up or arranged for read-only access to the CollectionSpace databases.

1. Download and install the Jaspersoft Studio application. This is free, open source software from Jaspersoft, which you can download from https://community.jaspersoft.com/project/jaspersoft-studio/releases.

2. Read the tutorials that you find useful: https://community.jaspersoft.com/wiki/jaspersoft-studio-tutorials-archive. 

3. Ensure you have access to the database. If you are working on the server that hosts CollectionSpace, the default configuration will allow access. Otherwise, you need to have your admin allow remote access to the database by editing the PostgreSQL configuration files:

   1. In the main postgresql.conf file, there must be an entry like:

      Code Block
      listen_addresses = 'localhost, {your-machine}' # what IP address(es) to listen on;

      where you or your administrator will replace "{your-machine}" with the IP address or hostname of the computer from which you will be connecting when you're authoring reports. See also the PostgreSQL documentation on Connections and Authentication.

   2. In PostgreSQL's host-based authentication file, pg_hba.conf, there must be an entry for a PostgreSQL database user account that will be given read-only privileges to the nuxeo database, for the purpose of performing queries and running reports. The following example specifies that access is granted to the nuxeo database to the PostgreSQL database user account named "reader," for remote connections from IP address 172.20.143.89, via username and password authentication (md5).

      Code Block
      host nuxeo reader 172.20.143.89/32 md5

      (In the example above, replace the example IP address given there with the actual IP address of the machine you will be connecting from. In place of specifying an individual IP address, you can instead specify a subnet range of addresses. For details, see the PostgreSQL documentation on the pg_hba.conf file..)

Writing a report

Follow the instructions in the CollectionSpace User Manual to create a project in Jaspersoft Studio and establish a connection to CollectionSpace: Creating and Running a CollectionSpace Report in Jaspersoft Studio.

...

When formatting fields, Jaspersoft allows for expressions to be used when formatting your fields. Reports will default to Java expressions and support for Groovy and JavaScript expressions are also provided:

...

other languages can be used by by setting language attribute in the header of the report jrxml, e.g.

<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" 
name="notice_inventory_completion" language="javascript" whenNoDataType="NoDataSection" ...>

Groovy and JavaScript are provided as part of the default CollectionSpace installation with the following versions:

...

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".

1. Create a report metadata record to register the report with CollectionSpace. This record contains information about the report, so that CollectionSpace knows how to run it. You will need to run a curl command to send the record to the server's REST API. The following example declares that the report "acq_basic.jrxml" should be shown to users when they are editing Acquisition records. Set the outputMIME value to the desired default output type for the report. This can be any output type supported by JasperReports.

<?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 is a sample Acquisition report.</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>

...

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

It's common to create reports that describe Object records that are related to a procedural record, such as an Intake. In this case, the context document is the procedural record (the Intake, Accession, etc.), even though the report will actually generate output about the related Object records. The forDocType values present in the XML above control where the user will see the report in the UI. You may infer from the XML above that one report can appear for multiple types of records -- this is useful when a report summarizes Objects associated with multiple kinds of procedural records (Intakes, Acquisitions, Loans, etc.). The value of the csid parameter passed to the report from CollectionSpace will be the unique id of the record on which the user ran the report (e.g., the Intake, or the Acquisition). Your report query must select Object records associated to that record through relations.

...

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

• Via the CollectionSpace user interface:

  • By clicking on a report from the "Reports" list in the sidebar of record editor screens. This list will display reports, if any, that you can run in the current context.

  • By selecting search results, and clicking on a report from the "Reports" list in the sidebar of search result screens. This list will display reports, if any, that you can run in the current context.

  • By selecting a report on the Tools/Reports screen, and clicking the "Run..." button. This allows you to select the context in which to run the report.

• Programmatically, via the Reporting Service REST APIs.

Deleting a report

To delete a report, use the Services Layer REST API to:

• Make a call to that API to list Report records.

• From that list, find the CSID of the relevant Report record.

• Make a second call to that API to delete that record, via its CSID.

The CRUD+L (Create, Read, Update, Delete, List) section of the Reporting Service RESTful APIs describes how to make these calls.

...