Web REST API

Product version:
6.0
Product edition:
  • Community
  • Teamwork
  • Efficiency
  • Performance

This page describes the Web API available for Web clients of Bonita BPM Engine. This API is used by the Bonita BPM Portal component of Bonita BPM 6.0. It provides access to the subset of the features exposed in the Bonita BPM Engine API that are used for managing resources.

The Web API is a REST API and uses the JSON (JavaScript Object Notation) data format. It communicates with the Bonita BPM Engine over HTTP, and it returns standard HTTP error codes.

As an alternative to using this Web REST API, it is also possible to access the Bonita BPM Engine APIs via HTTP. For details, see the Bonita BPM Development overview.

Authentication and initialization
List of APIs
List of resources
Create a resource
Read a resource
Update a resource
Delete resources
Search for a resource
Examples

Authentication and initialization

Calls to the Web REST API require you to first log in as a user registered in the Engine database. To log in, using the following request

Request URL http://host:port/bonita/loginservice
Request Method POST
Form Data username: a username
password: a password
redirect: false

Setting the redirect parameter to false indicates that the service should not redirect to Bonita Portal (after a successful login) or to the login page (after a login failure).

After you log in, get the translation resource for the current locale. This is used to return the appropriate language strings in subsequent calls.

Request URL http://host:port/bonita/API/system/i18ntranslation?f=locale%3dlocale-id
Request Method GET

In the request URL, locale-id is the two-letter code identifiying the locale. For example, to get the French-language resources, use a GET request with the URL http://localhost:8080/bonita/API/system/i18ntranslation?f=locale%3dfr.

To log out, use the following request:

Request URL http://host:port/bonita/logoutservice
Request Method GET
Form Data redirect: false

Setting the redirect parameter to false indicates that the service should not redirect to the login page after logging out.

List of APIs

The Web REST API contains the following APIs:

API Purpose
identity Manage information about the organization (users, groups, etc.). For example, add a user to a group.
system Manage session information and translations. For example, retrieve the translation for the current language.
portal Manage profiles, to configure the actions a user can perform. For example, assign the administrator profile to a user.
bpm Manage process elements. For example, retrieve a comment on a case.
platform Manage the platform. For example, stop the Bonita Engine.

List of resources

The following table shows the resources that are relevant to each API and gives the format of the resource identifier. Most resources have a simple identifier (marked simple in the table). Others have compound identifiers that indicate an association between resources.

API Resource Definition Identifier
identity user A person who performs a step in a process. simple
role A profile within a group (for example, manager). simple
group A subdivision of an organization. Groups can be nested. A user can belong to more than one group. simple
membership A mapping of user, group, and role, indicating that the user belongs to the group with the specified role. compound: user_id/group_id/role_id
professionalcontactdata Contact information for a user. specify the user_id
personalcontactdata Contact information for a user. specify the user_id
system i18nlocale The locale of the client simple
i18ntranslation

The map of translations for the current language simple
session Session information such as the username simple (can be anything, is not used to retrieve session because there cannot be more than one)
portal profile A set of permissions to access actions. simple
profileEntry An action that can be accessed by a user with this profile.

simple
profileMember A user that has this profile. simple
bpm humanTask A task in a process that is performed by a user. simple
userTask

A task in a process that is performed by a user. simple
archivedHumanTask A task in an archived instance of a process that was performed by a user. simple
archivedUserTask A task in an archived instance of a process that was performed by a user. simple
process A process. simple
category A name for a collection of processes. simple
processCategory A process that belongs to a category. compound: process_id/category_id
processConnector A connector for is used in a process. compound: process_id/connector_id
case An instance of a process. simple
archivedCase A completed instance of a process. simple
comment A comment attached to an active instance of a process. simple
archivedComment A comment attached to an archived instance of a process. simple
actor An actor assigned to a process or step. simple
actorMember A user mapped to an actor. simple
hiddenUserTask A task in a process that is to be performed by a user, which the user has hidden. simple
activity An activity (task, call activity, or subprocess). simple
archivedActivity An activity in an archived instance of a process. simple
task A task in a process. simple
archivedTask A task in an archived instance of a process. simple
archivedFlowNode A flow node (gateway or event) in an archived instance of a process. simple
processResolutionProblem An item in a process that needs to be resolved. simple
caseDocument A document attached to an instance of a process. compound: case_id/document_id
connectorInstance A connector attached to an instance of a process. simple
archivedConnectorInstance A connector attached to an archived instance of a process. simple
processConnectorDependency A dependency of a connector attached to a process. compound: process_id/connector_name/connector_version/filename
caseVariable A variable in an instance of a process. compound: case_id/variable_id
processParameter (for Teamwork, Efficiency, and Performance editions) A parameter associated with a process. compound: process_id/parameter_id
manualTask (for Teamwork, Efficiency, and Performance editions) A task in a process that is performed externally with its status recorded in the process. simple
archivedManualTask (for Teamwork, Efficiency, and Performance editions) A manual task in an archived instance of a process. simple

Create a resource

Use a POST request to create a new resource.

URL: http://.../REST/{API_name}/{resource_name}/

POST: an item in JSON

Response: the same item in JSON, containing the values provided in the posted item, completed with default values and identifiers provided by Bonita BPM Engine.

Read a resource

Use a GET request to get a copy of a resource.

URL: http://.../REST/{API_name}/{resource_name}/{id}

Example: http://.../REST/identity/user/5

Response: an item in JSON

With compound identifier

The order of the identifier parts for each resource type is given in the table above.

URL: http://.../REST/{API_name}/{resource_name}/{id_part1}/{id_part2}

Example: http://.../REST/identity/membership/5/12/24

Response: an item in JSON

Update a resource

Use a PUT request to modify a resource.

URL: http://.../REST/{API_name}/{resource_name}/{id}

Example: http://.../REST/identity/user/5

PUT: a map in JSON containing the new values for the attributes you want to change.

Response: the corresponding item in JSON with new values where you requested a modification.

With compound identifier

URL: http://.../REST/{API_name}/{resource_name}/{id_part1}/{id_part2}

Example: http://.../REST/identity/membership/5/12/24

PUT: a map in JSON containing the new values for the attributes you want to change.

Response: the corresponding item in JSON with new values where you requested a modification.

Delete resources

Use the DELETE request to remove multiple resources.

URL: http://.../REST/{API_name}/{resource_name}/

DELETE: A list of identifiers in JSON, for example ["id1","id2","id3"]. Compound identifiers are separated by '/' characters.

Example: http://.../REST/identity/membership/

Response: empty

Search for a resource

Use the GET request to search for a resource. The required object is specified with a set of filters. Results are returned in a paged list, and you can specify the page (counting from zero), the number of results per page (count), and the sort key (order).

URL: http://.../REST/{API_name}/{resource_name_plural}?p={page}&c={count}&o={order}&s={query}&f[]={filter_name}:{filter_value}&f[]=...

Example: http://.../REST/identity/user?p=0&c=10&o=firstname&s=test&f[]=manager_id:3

Response: an array of items in JSON

The available filters are the attributes of the item plus some specific filters defined by each item.

Examples

Create a user

Create a new user, John Doe, with username john.doe and password bpm. Return the user data, including the user id, serialized in JSON.

Request URL http://localhost:8080/bonita/API/identity/user/
Request Method POST
Request Payload {"userName":"john.doe","password":"bpm","password_confirm":"bpm","firstname":"John","lastname":"Doe"}
Response
{"id":"23","lastname":"Doe","firstname":"John","user_state":"ENABLED",
  "creation_date":"2013-05-16 17:27:41.424","created_by_user_id":"1", "userName":"john.doe",
  "last_update_date":"2013-05-16 17:27:41.424"...}

Assign a task

Assign the human task that has id 2 to the user John Doe, identified by his id, which is 23.

Request URL http://localhost:8080/bonita/API/bpm/humanTask/2
Request Method PUT
Request Payload {"assigned_id":"23"}
Response No response data (status code 200 if the update is successful)

List the pending tasks for a user

Retrieve a list of pending tasks for user John Doe, identified by his id, 23. The request is for a maximum of 10 tasks. The response below shows 2 tasks.

Request URL http://localhost:8080/bonita/API/bpm/humanTask?p=0&c=10&o=priority%20DESC&f=state%3dready&f=user_id%3d23&f=assigned_id%3d0&d=processId
Request Method GET
Request Payload empty
Response
[{"displayDescription":"task description","processId":"7818071982008935180",
  "state":"ready","type":"USER_TASK","assigned_id":"","assigned_date":"","id":"2",
  "executedBy":"0","caseId":"1","priority":"normal","description":"","actorId":"1", "name":"Step1",
  "reached_state_date":"2013-05-16 17:22:31.638", "displayName":"Step1","dueDate":"2013-05-16 18:22:31.606",
  "last_update_date":"2013-05-16 17:22:31.638"},
  {"displayDescription":"task description","processId":"7818071982008935180",
  "state":"ready","type":"USER_TASK","assigned_id":"","assigned_date":"","id":"4",
  "executedBy":"0","caseId":"2","priority":"normal","description":"","actorId":"1",
  "name":"Step1","reached_state_date":"2013-05-16 17:39:57.340", "displayName":"Step1",
  "dueDate":"2013-05-16 18:39:57.333","last_update_date":"2013-05-16 17:39:57.340"}]

In the request, the following parameters control the items returned:

  • p: index of the page to display
  • c: maximum number of elements to retrieve
  • o: sort order (descending priority in this example)
  • f: filters (state is ready, available to the user with id 23, and not assigned, in this example)
Last update on Apr, 8 2014