Process Engine REST Service

The Process Engine Client Installer deploys the Process Engine REST Service servlet in the IBM FileNet Workplace XT application. For specific platform dependencies and supported version numbers, refer to the IBM FileNet P8 Hardware and Software Requirements document for this release. To download this document from the IBM support page, see Accessing IBM FileNet Documentation.

The following diagram illustrates the fundamental architecture:

Process Engine REST Service Architecture

The Process Engine Java API is deployed to IBM FileNet Workplace XT to support the REST Service.

Authentication

The REST Service resource requests require the calling client to be authenticated with the application server container. HTTP Basic authentication is supported as the default authentication method. In addition, for Workplace XT deployment, LTPA Keys (Lightweight Third-Party Application Keys) for Single-Sign-On support in WebSphere is supported.

Note: The LDAP registry referenced must be the same registry used by the Content Engine.

The client's authorization for accessing REST operations on a specified resource is determined by the permissions assigned to the resource.

Resource Data Format

The REST Service resources use the JSON MIME type (content-type="application/json") and query string format for request and response data. Long query strings can be an exception to this (see URL Length Limitation below). All data needs to be in UTF-8 format (both for query strings and data in the request body).

Date Fields

For date fields, the value should be a string in the ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time. An example is: 2008-03-13T19:49:00Z.

URL Length Limitation

URLs used for GET operations with complex queries may result in long query strings. Browsers can handle relatively long request strings, but size may still be of concern. When this is the case, the client should detect this condition and change the GET request to a POST request. In the body of the POST request will be the query parameters (without "?"), and with the content type set to application/x-www-form-urlencoded.

For example, the POST statement:

POST /queues/{queue}/workbaskets/{workbasket}/queueelements
Content-Type=application/x-www-form-urlencoded

filters=[State=CA, City=Costa Mesa] &pageSize=50 &queryFlags=1 &orderBy=State &lastRecord = xxxxxx

is equivalent to the following GET statement:

GET /queues/{queue}/workbaskets/{workbasket}/queueelements?filters=[State=CA, City=Costa Mesa]&pageSize=50&queryFlags=1&orderBy=State& lastRecord =xxxxxx

Resource Navigation

When navigating between REST resources it is best practice to follow the URIs found in the response instead of manually constructing the URIs. This allows for future optimization, where the server can provide the optimal URI for navigating to a resource.

The base URI for all REST resources is:

    http://host:port/{context}/{servlet}/p8/bpm/v1/

This base is not included in the response URIs. Each client should be configured with the base URI. This base URI value can then be prepended to the URI found in the response.

Example

A client fetches the list of roles for the current user by navigating to the known URI:

    http://host:port/{context}/{servlet}/p8/bpm/v1/appspaces/{appspace}/myroles

The client receives the following JSON response for the myroles resource:

{
  "Agent":{"name":"Agent","URI":"appspaces/Autoclaim/roles/Agent"},
  "Manager":{"name":"Manager","URI":"appspaces/Autoclaim/roles/Manager"
}

The client then navigates to the Agent role by prepending the base URI to the value of the URI property in the response:

    "http://host:port/{context}/{servlet}/p8/bpm/v1/" + "appspaces/Autoclaim/roles/Agent"

Error handling

Errors recognized during the processing of a REST Service request, return an appropriate HTTP status code (such as, 200 OK or 404 Not Found).

Specifying a Locale

Use the Accept-Language HTTP Request Header field to specify the languages that are preferred as a response to the request. The Process Engine REST Service calls in to the Process Engine Java API, and uses the standard Process Engine XLIFF (XML Localization Interchange File Format) files for translation.

See Create an XLIFF file and Lookup precedence for locale resources for more information.