Brief Description

The Batch Job service allows the user to invoke batch jobs in a specific context, such as in the context of a single record, a list of records, or a group of records. Some batch jobs may also be invoked with no externally-provided context.

Batch jobs are written in Java, and conform to a specific Java interface. These jobs have access to a broad cross-section of the services RESTful APIs; they can create, update, delete and search records; relate records; and perform many other actions. The results (output) of the batch jobs are returned as service invocation responses.

Assumptions

Implementers can add batch jobs by creating new Java classes that implement the Batch Invocable (and hence, Invocable) interfaces.

A sample batch job, CreateAndLinkLoanOutBatchJob, is included in the batch module in the services source code repository.

This batch job demonstrates partial automation of the process of loaning out a CollectionObject. The job:

• Accepts the CSID of a single CollectionObject record as its invocation context.
• Creates a new Loan Out record.
• Relates that Loan Out record to the specified CollectionObject.
• Returns the CSID of the newly-created Loan Out record.

REST-based API

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

• Batch Job Service RESTful APIs#Batch Job CRUD+L services
• Batch Job Service RESTful APIs#Batch Job Invocation services
• Batch Job Service RESTful APIs#Batch Job REST payload schemas

Batch Job CRUD+L services

Create a Batch Job

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

POST /cspace-services/batch HTTP/1.1

Read a Batch Job

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

GET /cspace-services/batch/{id} HTTP/1.1

Update a Batch Job

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

PUT /cspace-services/batch/{id} HTTP/1.1

Delete a Batch Job

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

DELETE /cspace-services/batch/{id} HTTP/1.1

List Batch Job instances

Lists existing Batch Job records, with summary information for each. Follows standard List model. See the documentation of the Batch Job list schema, below. Example:

GET /cspace-services/batch/ HTTP/1.1

Filtering

In addition to the standard paging params, batch jobs can be filtered by various characteristics:

• doctype={document type name, e.g., CollectionObject, Intake, etc.}
• mode={single|list|group|nocontext}
• classname={classname}

For example, to get the batch jobs that can be invoked with a list of CollectionObjects:

GET /cspace-services/batch?doctype=CollectionObject&mode=list HTTP/1.1

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 batch jobs satisfying any of the filters are returned.

Batch Job Invocation services

Batch jobs are invoked using nearly the same REST API call - and identical payload schemas - to those used to invoke the Reporting service. For details, see Reporting Invocation services, substituting batch for reports in the URI in the POST example.

For the current schema for the payload used to invoke batch jobs and reports, see:

• Invocation schema

Batch Job REST payload schemas

Batch Job instance schema

Create and Update should use the following schema:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="batch">
  <ns2:batch_common xmlns:ns2="http://collectionspace.org/services/batch"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <supportsDocList>true</supportsDocList>
    <forDocTypes>
      <forDocType>CollectionObject</forDocType>
    </forDocTypes>
    <name>TestCreateAndLinkLoanOutBatchJob</name>
    <className>org.collectionspace.services.batch.nuxeo.CreateAndLinkLoanOutBatchJob</className>
    <supportsSingleDoc>true</supportsSingleDoc>
    <createsNewFocus>true</createsNewFocus>
    <notes>This should be interesting</notes>
  </ns2:batch_common>
</document>

Batch Job list schema

Batch Job uses the new abstract common list mechanism, allowing for some configuration of returned fields. By default, 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 xmlns:ns2="http://collectionspace.org/services/jaxb">
  <pageNum>0</pageNum>
  <pageSize>40</pageSize>
  <itemsInPage>1</itemsInPage>
  <totalItems>1</totalItems>
  <fieldsReturned>name|forDocType|uri|csid</fieldsReturned>
  <list-item>
    <csid>05e5c5cf-faad-427c-8220</csid>
    <uri>/batch/05e5c5cf-faad-427c-8220</uri>
    <name>TestCreateAndLinkLoanOutBatchJob</name>
    <forDocType>CollectionObject</forDocType>
  </list-item>
</ns2:abstract-common-list>