Skip to main content

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

  • Close [x]

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

  • Close [x]

developerWorks Community:

  • Close [x]

Using the REST APIs in IBM Business Process Manager V7.5

Nikhil Thaker, Advisory Software Engineer, IBM
Nikhil Thaker photo
Nikhil Thaker is anAdvisory Software Engineer with IBM Software Group, and a member of the product team that developed the BPM REST APIs for IBM Business Process Manager V7.5. He has more than ten years of experience in developing middleware, Enterprise Application Integration and business process management solutions. He has worked with various IBM customers as a consultant and lab advocate in EAI and BPM in the automotive, health care, telecommunication and utilities industries.

Summary:  Learn about the REST resources available for application developers to use in IBM® Business Process Manager to access business process, human task and business category data. This article introduces the various components of Business Process Manager that are exposed in the REST APIs, as well as supported content types, use of method overrides, response data formats, and how to use the REST API Tester tool.

Date:  31 Aug 2011
Level:  Intermediate PDF:  A4 and Letter (405 KB | 15 pages)Get Adobe® Reader®
Also available in:   Chinese  Korean

Activity:  27181 views
Comments:  

Overview

IBM Business Process Manager V7.5 provides a set of APIs that are implemented using Representational State Transfer (REST) services. A set of business process definition (BPD) related REST resources are provided for accessing business process, human task and business category data. These REST APIs enable developers to build a user interface or customize an existing portal application. The APIs are simple enough to be called from mobile devices or from Rich Internet Applications (RIAs).

This article introduces the IBM Business Process Manager REST APIs you can use to access business process, human task and business category data, and describes the various components of Business Process Manager that are exposed in the REST APIs. You'll learn about the following:

  • The REST URL format
  • The available REST APIs
  • Supported content types and use of method overrides
  • Response data formats
  • The REST API Tester

BPM components and data models

The Business Process Manager REST APIs work with various BPM components. Figure 1 illustrates all Business Process Manager components for which a REST APIs are implemented, and their associated data models.


Figure 1. BPM components and data models implemented by REST APIs
BPM components and data                     models implemented by REST API

Several REST methods are available for application developers to use on each resource; these methods are listed in the next section. Following is the list of Business Process Manager components in which various product functions are exposed in REST APIs:

  • Business process definitions
  • Process instances
  • Tasks
  • External activities and services
  • Users And groups
  • Saved searches and custom searches

Executing REST APIs

Before we dive into the specifics of what BPM REST APIs are supported by the Business Process Manager REST API specification, let's first take a look at the REST API URL and then try executing a simple REST API.

The REST API URL

The REST resource URLs have the following format: br / http://{host}:{port}/{context-root}/v1/{resource}?{query}

where

{host}:{port} is the host address and port of the REST API endpoint. For example, MyProcessServer:9080

{context-root} is the context root. All the REST APIs described in this article have the context root /rest/bpm/wle .

/v1 is the current version of the REST Resources.

{resource} is a resource identifier, such as "process," "task," and so on.

{query} contains query parameters that can be passed to the resource.

Execute a REST API using the REST API Tester

In this section, you'll use the REST API Tester provided in Business Process Manager to execute a simple REST API, so you can get a feel for what is offered in the Business Process Manager REST APIs. You can use the Tester tool invoke all the REST calls described in this article. You can access the tool by opening your browser to the following URL:

http://{host}:{port}/bpmrest-ui

where {host}:{port} is the host address and port of the REST API endpoint. For example, MyProcessServer:9080.

Now let's execute a simple REST API to obtain user details. To do this, complete the following steps:

  1. Open a web browser to the following URL, substituting the correct host and port information:
    http://{host}:{port}/bpmrest-ui.
  2. In the REST API Tester, select JSON (Javascript Format) for the ResultType field.
  3. In the Select API Call: area, select Organization API, then click User Details.
  4. Enter tw_admin in the User Name field.
  5. Click the Execute Call button. You'll see that the REST URL request is sent to the server and a response is displayed on the right pane of the Tester.

Figure 2. REST API Tester executing User Details REST API
REST API Tester executing User Details REST API

(See a larger version of Figure 2.)

The REST API Tester has the following features:

  • Acts as a client to all the server-side REST resources defined to support various Business Process Manager functions.
  • Has a web-based user interface that allows easy access to REST resources with a few mouse clicks.
  • Provides the ability to return JSON and XML data format.
  • Provides the ability to select any API available and to set any options available on the API.
  • Provides the ability to execute the API and see the result in a readable format.
  • Displays the URL (including parameter string) along with the results.

Business Process Manager REST API specification

This section lists all the available REST APIs defined in the Business Process Manager REST API specification, as shown in Figure 1.

BPD REST APIs

This section lists the REST APIs exposed for BPDs.

The legal values for parts are:

"all"|"none"|"header"|"dataModel"|"data"|"diagram"

You can filter an individual part of the data model or a retrieved list of parts using a separator. By default the REST API will retrieve all associated parts of the data model.


Table 1. Summary of all BPD methods
Protocol methodREST API URLDescription
GET /v1/processModel/{bpdId}[?snapshotId={string}][&processAppId={string}][&parts={string}] Use this method to retrieve a BPD model.
POST /v1/process?action={string}&bpdId={string}[&snapshotId={string}][&processAppId={string}] Use this method to start a BPD.
POST /v1/process?action={string}&message={string} Use this method to post a message to the Event Manager for asynchronous processing.
GET /v1/processApps Use this method to retrieve the process applications that are installed in the system.

Business process instance REST APIs

This section lists all the REST APIs exposed for business process instances.

The legal values for action query parameters for BPD instance data are:

"suspend", "terminate", "comment", "adhoc", "addDocument", "updateDocument", 
"sendMessage", "fireTimer", "delete", "deleteDocument", "trigger"

When the action query parameters are used, the REST resource will invoke the appropriate action handler.


Table 2. Summary of all business process instance REST APIs
Protocol methodREST API URLDescription
GET /v1/process/{instanceId} Use this method to retrieve details of a specified process instance.
PUT /v1/process/{instanceId}?action={string} Use this method to perform one of the following actions on a process instance: suspend, resume, terminate.
PUT /v1/process/{instanceId}?action={string}&dueDate={string} Use this method to update the due date of a process instance.
PUT /v1/process/{instanceId}?action={string}&docId={string}[&data={string}][&docUrl={string}] Use this method to update an existing document associated with a process instance.
PUT /v1/process/{instanceId}?action={string}&step={string} Use this method to run an adhoc event associated with a process instance.
PUT /v1/process/{instanceId}?action={string}&script={string} Use this method to execute a JavaScript expression and return the resulting process instance details.
DELETE /v1/process/{instanceId}?action={string}&docId={string} Use this method to delete a document associated with a process instance.
POST /v1/process/{instanceId}?action={string}&comment={string} Use this method to add a comment to a process instance.
POST /v1/process/{instanceId}?action={string}&timerId={string} Use this method to manually fire an inline or attached timer.
POST /v1/process/{instanceId}?action={string}&docType={string}&name={string}[&data={string}][&docUrl={string}] Use this method to add a new document to a process instance.
POST /v1/process/{instanceId}?action={string}&docId={string}[&data={string}][&docUrl={string}] Use this method to update an existing document associated with a process instance.
POST /v1/process/{instanceId}?action={string}&docId={string} Use this method to delete a document associated with a process instance.
GET /v1/processes/queries[?kind={string}][&content={string}] Use this method to retrieve a list of queries for process instance data.
GET /v1/processes/query/{queryName}/attributes Use this method to retrieve a list of attributes of a query for process instance data.
GET /v1/processes/query/{queryName}[?selectedAttributes={string}][&queryFilter={string}][&sortAttributes={string}][&offset={integer}][&size={integer}] Use this method to retrieve a list of process instance entities via a query.
GET /v1/processes/query/{queryName}/count[?queryFilter={string}][&offset={integer}][&size={integer}] Use this method to retrieve the number of process instance entities in a query matching specified criteria.

Task REST APIs

This section lists all the REST APIs exposed for a task on a process server.

The legal values for action query parameters for task REST APIs are:

"start", "assign", "update", "finish", "claim", "claimnext",  "cancel" and "getnext"

When the action query parameters are used, the REST resource will invoke the appropriate action handler.


Table 3. Summary of all task REST APIs
Protocol methodREST API URLDescription
GET /v1/taskTemplate/{templateId} Use this method to retrieve a specific human task template.
GET /v1/taskTemplate/{templateId}/clientSettings/{type} Use this method to retrieve client settings for a human task template.
GET /v1/taskTemplates/queries[?kind={string}][&content={string}] Use this method to retrieve a list of queries for task template data.
GET /v1/taskTemplates/query/{queryName}/attributes Use this method to retrieve a list of attributes of a query for task template data.
GET /v1/taskTemplates/query/{queryName}[?interactionFilter={string}][&selectedAttributes={string}][&sortAttributes={string}][&offset={integer}][&size={integer}] Use this method to retrieve a list of task template entities via a query.
GET /v1/taskTemplates/query/{queryName}/count[?interactionFilter={string}][&offset={integer}][&size={integer}] Use this method to retrieve the number of task template entities in a query matching specified criteria.
GET /v1/externalactivity/{externalActivityId}/model[?parts={string}] Use this method to retrieve the model information for an external activity.
PUT /v1/task?action={string} Use this method to claim responsibility for multiple task instances.
PUT /v1/task?action={string} Use this method to release multiple claimed task instances.
PUT /v1/task?action={string}&query={string}[&queryFilter={string}][&sortAttributes={string}] Use this method to claim the next task, selected based on filter criteria. If a task exists that is already claimed, that task is returned.
GET /v1/task/actions?taskIDs={string}[&actions={string}] Use this method to retrieve available actions for human tasks.
GET /v1/task/{taskId}[?parts={string}] Use this method to retrieve details of a specified human task.
PUT /v1/task/{taskId}?action={string} Use this method to start a task.
PUT /v1/task/{taskId}?action={string}[&toMe={boolean}][&back={boolean}][&toUser={string}][&toGroup={string}][&parts={string}] Use this method to assign a task to a user or group.
PUT /v1/task/{taskId}?action={string}[&dueDate={string}][&priority={string}][&parts={string}] Use this method to update a task's due date or priority.
PUT /v1/task/{taskId}?action={string}[&parts={string}][params={string}] Use this method to finish, or close a task.
PUT /v1/task/{taskId}?action={string} Use this method to claim, cancel, or perform another action on a task.
GET /v1/task/{taskId}/clientSettings/{type} Use this method to retrieve client settings for a human task instance. This consists mainly of the URL to be used to invoke the coach associated with the task.
GET /v1/tasks/queries[?kind={string}][&content={string}] Use this method to retrieve a list of queries for task instance data.
GET /v1/tasks/query/{queryName}/attributes Use this method to retrieve a list of attributes of a specified query for containing task instance data.
GET /v1/tasks/query/{queryName}[?selectedAttributes={string}][&interactionFilter={string}][&queryFilter={string}][&sortAttributes={string}][&offset={integer}][&size={integer}] Use this method to retrieve a list of task instance entities via a query.
GET /v1/tasks/query/{queryName}/count[?interactionFilter={string}][&queryFilter={string}][&offset={integer}][&size={integer}] Use this method to retrieve the number of task instance entities in a query matching specified criteria.

Services REST APIs

This section lists all the REST APIs exposed for a service on a process server.

The legal values for action query parameters for service REST APIs are:

"resume", "stop", "currentlyRunning", "getData", "setData", "js"

When the action query parameters are used, the REST resource will invoke the appropriate action handler.


Table 4. Summary of all services REST APIs
Protocol methodREST API URLDescription
GET /v1/serviceModel/{serviceId}[?parts={string}] Use this method to retrieve a service model.
POST /v1/service/{instanceId}?action={string}[&createTask={boolean}][&parts={string}] Use this method to start a service. The instanceId parameter should be specified as either the service model ID, or a string in the form: <project-shortname>@<service-name>.
GET /v1/service/{instanceId} Use this method to retrieve the list of currently running services. The parameter should be specified as the string currentlyRunning.
GET /v1/service/{instanceId}?action={string}[&parts={string}] Use this method to retrieve data associated with a service. The parameter should be specified as the service instance ID. This value is returned as the key element within the ServiceRunModel response when starting a service.
PUT /v1/service/{instanceId}?action={string} Use this method to stop a running service. The parameter should be specified as the service instance ID. This value is returned as the key element within the ServiceRunModel response when starting a service.
PUT /v1/service/{instanceId}?action={string}[&parts={string}] Use this method to resume a stopped service. The parameter should be specified as the key element within the ServiceRunModel response when starting a service.
PUT /v1/service/{instanceId}?action={string}&script={string} Use this method to evaluate a javascript code fragment in the context of a running service instance. The parameter should be specified as the service instance ID. This value is returned as the key element within the ServiceRunModel response when starting a service.
PUT /v1/service/{instanceId}?action={string}&field={string}&value={string} Use this method to set a field within a running service. The parameter should be specified as the service instance ID. This value is returned as the key element within the ServiceRunModel response when starting a service.

User and group REST APIs

This section lists all the REST APIs exposed for defined users and groups on a process server.


Table 5. Summary of all user and group REST APIs
Protocol methodREST API URLDescription
GET /v1/exposed Use this method to retrieve items that are exposed to an end user. All exposed items of type "process" (BPD), "service", "report", and "scoreboard" are returned.
GET /v1/exposed/{type} Use this method to retrieve items of a specific type that are exposed to an end user.
GET /v1/users[?filter={string}][&parts={string}] Use this method to retrieve information about users that have been defined to the Business Process Manager installation.
GET /v1/user/{userNameOrID}[?parts={string}] Use this method to retrieve information about a user that has been defined to the Business Process Manager installation.
PUT /v1/user/{userNameOrID}?action={string}&key={string}&value={string} Use this method to update the user preferences associated with a user, using action ="setPreference".
GET /v1/groups[?filter={string}][&parts={string}] Use this method to retrieve information about groups that have been defined to the Business Process Manager installation.
GET /v1/group/{groupNameOrID}[?parts={string}] Use this method to retrieve information about a user that has been defined to the Business Process Manager installation.
GET /v1/systems Use this method to retrieve metadata about one or more Business Process Manager installations (single server or cluster).

Saved and custom searches REST APIs

This section lists all the REST APIs exposed for saved and custom searches defined in a process server.


Table 6. Summary of all search REST APIs
Protocol methodREST API URLDescription
GET /v1/search/meta/{type} Use this method to retrieve the metadata of the requested type via the type path parameter.
PUT /v1/search/query[?columns={string}][&condition={string}][&sort={string}][&secondSort={string}][&organization={string}][&saveAsName={string}] Use this method to perform a custom search.
GET /v1/performance/query?filter={string}[&columns={string}][&condition={string}][&sort={string}][&secondSort={string}][&onlyRollup={string}][&rollupRule={string}] Use this method to perform a custom search against the performance server. Note that searches performed against the performance server return only the most recent available values for business data. To retrieve the previous values of business data, refer to the performance instance search resource. See the Business Process Manager Information Center for more information.
GET /v1/performance/instance/{piid} Use this method to retrieve the history information for a process instance.


Method agnostics for mobile support

All Business Process Manager REST APIs that start with the context-root /rest/bpm/wle are HTTP method agnostic and will support either an HTTP GET or an HTTP POST method. For example, a documented REST API that is supported with a PUT or DELETE has an equivalent POST method support. This is done to ensure that mobile and other devices that do not support the PUT HTTP method can use HTTP POST to invoke a REST resource.

Using HTTP method override

Some firewalls do not allow the use of HTTP PUT and DELETE methods to flow through the firewall because of security considerations. To accommodate this, a PUT or DELETE request can be "tunneled" through a POST request using the X-Method-Override or X-HTTP-Method-Override HTTP header. In general, X-Method-Override and X-HTTP-Method-Override HTTP headers override the HTTP method used in the request.

As an alternative to setting the X-Method-Override or X-HTTP-Method-Override HTTP headers, you can use the x-method-override or x-http-method-override URL query parameters. For example, "POST /rest/bpm/htm/v1/task?...&x-method-override=PUT").


Supported data formats for Business Process Manager REST APIs

The Business Process Manager REST APIs support three data formats:

  • JSON (JavaScript Object Notation)

    This is the default response content type. For the detailed format of each returned object, see the JSON schema specifications for each operation. See the Business Process Manager Information Center for more information.

  • XML (eXtensible Markup Language)

    The format of XML-based data is specfied by the XML schemas supplied with the product in the <install-root>/properties/schemas/bpmrest/v1 directory. Excerpts of these schemas are also provided in the documentation for each operation.

    Response validation tip

    The Business Process Manager REST resources use JAXB data binding technology to marshal and demarshal XML. Thus, you can choose to validate the REST XML response against the provided schema definitions.

  • JSONP (JSON with Padding)

    This format can be used as an alternative to JSON. In this case, each returned JSON response is wrapped in a JavaScript callback function invocation. To use this feature, you must also specify the callback URI query parameter.

Switching data formats

There are two ways to switch the default data format:

  • A client can specify the requested media type for the response by using the Accept HTTP header. For example: "Accept: application/json"

  • Alternatively, the client may use the accept URI query parameter. For example, "GET /rest/bpm/htm/v1/task/...?accept=application/json").

If both the HTTP header and the URI query parameter are specified, the query parameter takes precedence. If the server is unable to respond with the requested media type, then an HTTP status code of "406 Not Acceptable" is returned.

JSONP response:

Enabling JSONP tip

By default, the support for JSONP is disabled due to security considerations. To enable JSONP support, you must set the following property in the server's 100Custom.xml file:
<jsonp-enabled>true</jsonp-enabled>

To request that response data be returned in the JSONP format, you must specify a response media type of application/x-javascript with either the Accept HTTP header or the Accept URI query parameter, and you must also specify the JavaScript function name with the callback URI query parameter. In this case, the response consists of the JSON content wrapped in a JavaScript callback function invocation. For example, GET /rest/bpm/wle/v1/task/...?accept=application/x-javascript&callback=mycallback


Response data model

The Business Process Manager REST APIs have a well-defined response data model. The response data will always have a status and data filed. Status will indicate HTTP status code and data filed will hold either the response data or error information. The following listings show a sample JSON response.


Listing 1. Response data model sample

{ status:, data:}


Listing 2. Response for currentUser REST API in JSON format
			
{
   "status":"200",
   "data":{
	 "userID":1,
	 "userName":"tw_admin
   }
}
			


Listing 3. Response for currentUser REST API in XML format
			
<bpm:ResponseData xmlns:bpm="http://rest.bpm.ibm.com/v1/data">
   <status>200</status>
   <data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xmlns:ug="http://rest.bpm.ibm.com/v1/data/usergroup" 
            xsi:type="ug:User">
      <userID>1</userID>
   </data>
</bpm:ResponseData>
			


Error response

The Business Process Manager REST APIs have a well-defined error response data model. The error response data will always contain a status and additional data. The status will indicate an error and the data will contain information on the exception type, the error number, error message and programmer details. The following listings show examples of JSON and XML error responses.


Listing 4. Error response in JSON format
			
{
   "status":"error",
   "Data":{
    "status":"error",
	"exceptionType":"com.ibm.bpm.wle.api.NoSuchUserException",
	"errorNumber":"CWTBG0007E",
	"errorMessage":"CWTBG0007E: User 'currentUser' not found.",
	"errorMessageParameters":["currentUser"]
	}
}
			

By default, an error response will omit the server-side exception details due to security considerations. To enable the inclusion of server-side exception details, you must set the following property in the server's 100Custom.xml file:
<server-stacktrace-enabled>true</server-stacktrace-enabled>


Listing 5. Error response in XML format
			
<ex:RestRuntimeException 
       xmlns:ex="http://rest.bpm.ibm.com/v1/data/exception">
   <status>error</status>
   <Data>
      <status>error</status>
	  <exceptionType>com.ibm.bpm.wle.api.NoSuchUserException</exceptionType>
	  <errorNumber>CWTBG0007E</errorNumber>
	  <errorMessage>CWTBG0007E: User 'currentUser' not found.</errorMessage>
	  <errorMessageParameters>currentUser</errorMessageParameters>
   </Data>
</ex:RestRuntimeException>
			


Summary

The IBM Business Process Manager REST APIs enable customers to build custom user interfaces or add BPM functions to an existing company portal without having to resort to hacks or unsupported calls. These APIs are simple enough to work with a Rich Internet Applications (RIAs) or mobile devices. The REST APIs are delivered with a REST API Tester that you can use to verify results during application development.


Acknowledgements

The author would like to thank to Steven Gonchar for his code contribution in building the REST API Tester, Gregory Harley for putting together the IBM Business Process Manager REST specification and contributing to this article content, and Phil Adams and Richard Scheuerle for reviewing the article.


Resources

About the author

Nikhil Thaker photo

Nikhil Thaker is anAdvisory Software Engineer with IBM Software Group, and a member of the product team that developed the BPM REST APIs for IBM Business Process Manager V7.5. He has more than ten years of experience in developing middleware, Enterprise Application Integration and business process management solutions. He has worked with various IBM customers as a consultant and lab advocate in EAI and BPM in the automotive, health care, telecommunication and utilities industries.

Report abuse help

Report abuse

Thank you. This entry has been flagged for moderator attention.


Report abuse help

Report abuse

Report abuse submission failed. Please try again later.


developerWorks: Sign in


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


Rate this article

Comments

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=754956
ArticleTitle=Using the REST APIs in IBM Business Process Manager V7.5
publish-date=08312011