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:
The Process Engine Java API is deployed to IBM FileNet Workplace XT to support the REST Service.
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.
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).
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.
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
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.
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"
Errors recognized during the processing of a REST Service request, return an appropriate HTTP status code (such as, 200 OK or 404 Not Found).
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.