Reporting Service RESTful APIs

Owned by Jessi Weithman
Apr 18, 2024
Reporting Service Home

Brief Description

Error rendering macro 'excerpt-include' : No link could be created for 'Reporting Service Description and Assumptions'.
For a full description, visit the Service Description and Assumptions page.

Assumptions

For a complete list of assumptions, visit the Service Description and Assumptions page.

Report Contexts

Reports are defined to support various types or modes of context, including a single CSID, a list of CSID values, or a group CSID (that has an associated list of objects). In addition, the context specifies one more more document (a.k.a. "Record") types. The primary function of the context allows the application to filter the full list of reports so that the UI will only display reports that make sense in the context of what the user is currently doing. Thus, e.g., if the user is editing an Intake record, the application can query the services for the set of reports that support a singleCSID context with the document type "Intake."

Some reports may also support invocation with no context (e.g., a report that queries for all terms in the configured authorities that have status "Proposed"). These are defined to support "NoContext."

REST-based API

The Reporting Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual Reporting instances, plus list operations on multiple Reporting instances. These follow the Common model for CollectionSpace REST services.

Reporting CRUD+L services

Create a Report

Creates a new Report record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Report record. Follows standard Create model. See the documentation of the Report schema, below. Example:

POST /cspace-services/reports HTTP/1.1
Read a Report

Reads an existing Report record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Report schema, below. Example:

GET /cspace-services/reports/{id} HTTP/1.1
Update a Report

Updates an existing Report record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Report schema, below. Example:

PUT /cspace-services/reports/{id} HTTP/1.1
Delete a Report

Deletes an existing Report record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

DELETE /cspace-services/reports/{id} HTTP/1.1
List Report instances

Lists existing Report records, with summary information for each. Follows standard List model, including support for the query parameter "kw=term" for keyword search (useful to search on the name and description). Filtering on report characteristics is also supported. See also the documentation of the Report list schema, below. Example:

GET /cspace-services/reports/ HTTP/1.1
Filtering

Three additional search parameters are supported, to filter the list of available reports. This is designed to support applications that want to present the reports appropriate to a given UI context. The query parameters are:

  • To filter by the mode of invocation, the query parameter "mode={single|list|group|nocontext}" specifies the mode that reports must support to be returned in the list results.
  • To filter by the doctype of invocation, the query parameter "doctype={doctype}" specifies the name of the document type (a.k.a. record type) that reports must support to be returned in the list results.
  • To filter by the filename of the report, the query parameter "filename={filename}" specifies the filename the report must have to be returned in the list results.

Note that reports can support more than one mode and/or docType, and different values for these filters will not produce mutually exclusive results (a given report may be returned in multiple filtered lists).

If multiple filter parameters are supplied, the filters are by default combined using an AND operator, so the results must satisfy all of the specified filters. This can be changed by adding the combine=or parameter to the list request. Setting combine to or causes the supplied filters to be combined using an OR operator, so reports satisfying any of the filters are returned.

Reporting Invocation services

Invoke a Report with no context

Invokes a Report to produce a new instance of the output. When invoked without context, a simple resource is available:

GET /cspace-services/reports/{id}/output HTTP/1.1

If the specified report does not support invocation with "NoContext", an error will be returned.

Invoke a Report with context

Invokes a Report to produce a new instance of the output.

POST /cspace-services/reports/{id} HTTP/1.1

The invocation payload uses the following simple schema. E.g., to invoke with a single Intake:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:invocationContext xmlns:ns2="http://collectionspace.org/services/common/invocable">
  <mode>single</mode>
  <docType>Intake</docType>
  <singleCSID>605e9252-598d-4459-8380</singleCSID>
</ns2:invocationContext>

To invoke with a list of CollectionObjects:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:invocationContext xmlns:ns2="http://collectionspace.org/services/common/invocable">
  <mode>list</mode>
  <docType>CollectionObject</docType>
  <listCSIDs>
    <csid>605e9252-598d-4459-8380</csid>
    <csid>9252605e-1234-2345-3456</csid>
 </listCSIDs>
</ns2:invocationContext>

To invoke with a group of CollectionObjects, use the following. Note that while the Group is a distinct type of record, the docType specifies the type of related documents that the group contains, and that the report is authored for.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:invocationContext xmlns:ns2="http://collectionspace.org/services/common/invocable">
  <mode>group</mode>
  <docType>CollectionObject</docType>
  <groupCSID>605e9252-598d-4459-8380</groupCSID>
</ns2:invocationContext>

If the specified report does not support invocation with the passed context (either the mode or the docType), an error will be returned.

If an error occurs within the report (e.g., if the passed CSID is not of the correct type, or there is an error in the SQL in the report definition), an error will be returned.

Reporting REST payload schemas

Reporting instance schema

The schemas below are severely abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Report records, please see the most recent Report record schema.

Create and Update should use the following schema:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:reports_common>
    <name>Acquisition Summary</name>
    <notes>Just a few fields about a single acquisition</notes>
    <outputMIME>application/pdf</outputMIME>
    <filename>acq_single.jasper</filename>
    <supportsNoContext>false</supportsNoContext>
    <supportsSingleDoc>true</supportsSingleDoc>
    <supportsDocList>false</supportsDocList>
    <supportsGroup>false</supportsGroup>
    <forDocTypes>
        <forDocType>Acquisition</forDocType>
        <forDocType>Intake</forDocType>
    </forDocTypes>
</ns2:reports_common>

Read will return the following schema (in addition to the standard collectionspace_core and account permission schemas):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:reports_common>
    <name>Acquisition Summary</name>
    <notes>Just a few fields about a single acquisition</notes>
    <outputMIME>application/pdf</outputMIME>
    <filename>acq_single.jasper</filename>
    <supportsNoContext>false</supportsNoContext>
    <supportsSingleDoc>true</supportsSingleDoc>
    <supportsDocList>false</supportsDocList>
    <supportsGroup>false</supportsGroup>
    <forDocTypes>
        <forDocType>Intake</forDocType>
    </forDocTypes>
</ns2:reports_common>
Reporting list schema

List (and variants) will return the following schema. This schema includes the uri and csid fields to help facilitate access to individual records:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:abstract-common-list>
    <pageNum>0</pageNum>
    <pageSize>40</pageSize>
    <itemsInPage>1</itemsInPage>
    <totalItems>1</totalItems>
    <fieldsReturned>csid|uri|updatedAt|name</fieldsReturned>
    <list-item>
        <csid>48fab3cf-dbd1-4b67-b4a7</csid>
        <uri>/reports/48fab3cf-dbd1-4b67-b4a7</uri>
        <updatedAt>2011-07-20T21:05:00Z</updatedAt>
        <name>Acquisition Summary</name>
    </list-item>
</ns2:abstract-common-list>