This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

BPMN REST API

Owned by Former user (Deleted)
Last updated: Feb 14, 2018 by Former user (Deleted)
12 min read

The Business Process Management Initiative (BPMI) has developed a standard Business Process Modelling Notation (BPMN). The BPMN 2.0 specification was released to the public in January 2011. The Business Process Profile of WSO2 Enterprise Integrator is powered by the Activiti engine 5.21.0, which is a light-weight workflow and Business Process Management (BPM) platform targeted at business people, developers, and system admins. It is open source and distributed under the Apache license. Activiti runs in any Java application, on a server, on a cluster or in the cloud. It is extremely lightweight and is based on simple concepts.

Only the core functionality of the REST API is addressed in this topic. In addition to the functionality mentioned in this topic, there is more REST API functionality as well. All this additional functionality is provided via the Activiti REST API. Take a look at the Activiti User Guide for more information.

Note

If you want to create your own external web application using the BPMN REST API, see the following Sample BPMN Explorer Jaggery Application.

Do the following to access the WSO2 Business Process Server REST services.

  1. Download WSO2 Enterprise Integrator and start the Business Process Profile.

  2. To access the BPMN REST service, you can use the following URL pattern: https://localhost:9445/bpmn/{serviceName}. Note that the REST API is secured using http basic authentication mechanism. 

    For example, the following service name lists all deployments: repository/deployments. So, the complete service URL to retrieve all deployments would be: https://localhost:9445/bpmn/repository/deployments

    If the user resides in a secondary userstore, in the http basic authentication header the username should be in the following format: <DOMAIN>/<USER>. E.g., foo/user1

The following sections expand on the various BPMN REST services.

Deployments

This REST service represents deployments already present in the process repository. A deployment is a container for resources such as process definitions, images, forms, etc. When a deployment is 'deployed' through the RuntimeService, the Activiti engine will recognize certain of such resource types and act upon them (e.g., process definitions will be parsed to an executable Java artifact). A deployment by itself is a read-only object and its content cannot be changed after deployment.

List of Deployments
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/repository/deployments
Sample URLhttps://localhost:9445/bpmn/repository/deployments
DetailsThis request retrieves all the deployments from the server.
Success Response Body
{
  "data": [
    {
      "id": "27501",
      "name": "sampleJavaServiceTask.bpmn20.xml",
      "deploymentTime": "2015-03-08T18:46:14.898+05:30",
      "category": null,
      "url": "https:\/\/localhost:9445\/bpmn\/repository\/deployments\/27501",
      "tenantId": ""
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "id",
  "order": "asc",
  "size": 1
}
Get a Deployment
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/repository/deployments/{deploymentId}
Sample URLhttps://localhost:9445/bpmn/repository/deployments/27501
DetailsThis request retrieves a specific deployment from the server.
Success Response Body
{
  "id": "27501",
  "name": "sampleJavaServiceTask.bpmn20.xml",
  "deploymentTime": "2015-03-08T18:46:14.898+05:30",
  "category": null,
  "url": "https:\/\/localhost:9445\/bpmn\/repository\/deployments\/27501",
  "tenantId": ""
}

Process definitions

Process definitions are an object structure representing an executable process composed of activities and transitions. Business processes are often created with graphical editors that store the process definition in a certain file format. These files can be added to a deployment artifact, such as a Business Archive (.bar) file. At the time of deployment, the engine will then parse the process definition files to an executable instance of this class, that can be used to start a ProcessInstance.
 

List of Process Definitions
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/repository/process-definitions
Sample URLhttps://localhost:9445/bpmn/repository/process-definitions
Details

This request retrieves all the process definitions from the server.

Note: You can use this request when you need to find a processDefinitionID or processDefinitionKey to be sent with a request. In the response body below, 'id' is the processDefinitionId and 'key' is the processDefinitionKey.

Success Response Body
{
  "data": [
    {
      "id": "sampleJavaServiceTask:1:27503",
      "url": "https:\/\/localhost:9445\/bpmn\/repository\/process-definitions\/sampleJavaServiceTask%3A1%3A27503",
      "key": "sampleJavaServiceTask",
      "version": 1,
      "name": null,
      "description": null,
      "deploymentId": "27501",
      "deploymentUrl": "https:\/\/localhost:9445\/bpmn\/repository\/deployments\/27501",
      "resource": "https:\/\/localhost:9445\/bpmn\/repository\/deployments\/27501\/resources\/sampleJavaServiceTask.bpmn20.xml",
      "diagramResource": null,
      "category": "https:\/\/www.bpmnwithactiviti.org",
      "graphicalNotationDefined": false,
      "suspended": false,
      "startFormDefined": false
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "name",
  "order": "asc",
  "size": 1
}
Get a Process Definition
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/repository/process-definitions/{processDefinitionId}
Sample URL

https://localhost:9445/bpmn/repository/process-definitions/sampleJavaServiceTask:1:27503

Details

This request retrieves a specific process definition based on the specified process definition Id.

Success Response Body
{
      "id": "sampleJavaServiceTask:1:27503",
      "url": "https:\/\/localhost:9445\/bpmn\/repository\/process-definitions\/sampleJavaServiceTask%3A1%3A27503",
      "key": "sampleJavaServiceTask",
      "version": 1,
      "name": null,
      "description": null,
      "deploymentId": "27501",
      "deploymentUrl": "https:\/\/localhost:9445\/bpmn\/repository\/deployments\/27501",
      "resource": "https:\/\/localhost:9445\/bpmn\/repository\/deployments\/27501\/resources\/sampleJavaServiceTask.bpmn20.xml",
      "diagramResource": null,
      "category": "https:\/\/www.bpmnwithactiviti.org",
      "graphicalNotationDefined": false,
      "suspended": false,
      "startFormDefined": false
 }

Process instances

This represents one execution of a process definition.

List of Process Instances
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/process-instances
Sample URLhttps://localhost:9445/bpmn/runtime/process-instances
Details

This request retrieves all the process instances from the server.

Success Response Body
 "data": [
    {
      "id": "27504",
      "url": "https:\/\/localhost:9445\/bpmn\/runtime\/process-instances\/27504",
      "businessKey": null,
      "suspended": false,
      "ended": false,
      "processDefinitionId": "sampleJavaServiceTask:1:27503",
      "processDefinitionUrl": "https:\/\/localhost:9445\/bpmn\/repository\/process-definitions\/sampleJavaServiceTask%3A1%3A27503",
      "activityId": "waitState",
      "variables": [
        
      ],
      "tenantId": "",
      "completed": false
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "id",
  "order": "asc",
  "size": 1
}
Get a Process Instance
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/process-instances/{proccessInstanceId}
Sample URLhttps://localhost:9445/bpmn/runtime/process-instances/27504
Details

This request retrieves a specific process instance based on the specified process instance Id.

Success Response Body
{
  "id": "27504",
  "url": "https:\/\/localhost:9445\/bpmn\/runtime\/process-instances\/27504",
  "businessKey": null,
  "suspended": false,
  "ended": false,
  "processDefinitionId": "sampleJavaServiceTask:1:27503",
  "processDefinitionUrl": "https:\/\/localhost:9445\/bpmn\/repository\/process-definitions\/sampleJavaServiceTask%3A1%3A27503",
  "activityId": "waitState",
  "variables": [
    
  ],
  "tenantId": "",
  "completed": false
}
Start a Process Instance
Request TypePOST
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/process-instances
Details

This request starts a process instance. A process instance can be started using the process definition id or process definition key or message. You need to specify either the processDefinitionId, or the processDefinitionKey or the message in the request body. Parameters businessKey, variables and tenantId are optional.

Note: It is not necessary to send in all the variables to start the process instance, sending a request body with only the processDefinitionId, processDefinitionKey or message should suffice. When sending a request body with the processDefinitionKey or message, providing the tenantId is mandatory.

It is not recommended to start a process instance using a message because it might not be able to uniquely identify a process instance.

Request Body

Request body (start by process definition Id):

{
   "processDefinitionId":"sampleJavaServiceTask:1:27503",
   "businessKey":"myBusinessKey",
   "variables": [
      {
        "name":"myVar",
        "value":"This is a variable"
      }
   ]
}

Request body (start by process definition key):

{
   "processDefinitionKey":"sampleJavaServiceTask",
   "businessKey":"myBusinessKey",
   "tenantId": "tenant1",
   "variables": [
      {
        "name":"myVar",
        "value":"This is a variable"
      }
   ]
}

Request body (start by message):

{
   "message":"newOrderMessage",
   "businessKey":"myBusinessKey",
   "tenantId": "tenant1",
   "variables": [
      {
        "name":"myVar",
        "value":"This is a variable"
      }
   ]
}
Activate or Suspend a Process Instance
Request TypePUT
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/process-instances/{proccessInstanceId}
Details

This request is used to activate a suspended process instance or vice versa.

Send a PUT request with the given respective request body as indicated below to activate or suspend the process instance. The response body of the request will be the same.

Request Body

Request body (activate a process instance):

{
   "action":"activate"
}

Request body (suspend a process instance):

{
   "action":"suspend"
}
Query a Process Instance
Request TypePOST
Request URLhttps://<Host Name>:<Port>/bpmn/query/process-instances
Details

This request is used to query or find a specific process instance using any of the attributes of the process instance. The request body depicts how to query for a process instance using the processDefinitionKey. You can also use the processDefinitionID to query for a specific process instance. 

You can retrieve the processDefinitionKey or processDefinitionID using the List Process Definitions service.

When querying a process instance using the processDefinitionKey, providing the tenantID is mandatory.

Request Body
{
  "processDefinitionKey":"sampleJavaServiceTask"
}
Delete a Process Instance
Request TypeDELETE
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/process-instances/{proccessInstanceId}
Sample URLhttps://localhost:9445/bpmn/runtime/process-instances/27503
Details

This request is used to delete a process instance using the process instance id to identify it. A process instance can only be deleted if all the tasks underneath that process instance are completed or removed. There is no response body provided when you delete a deployment, but the service status “204” indicates the deployment was found and deleted. A service status of “404” indicates the deployment was not found.

List of Variables of a Process Instance
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/process-instances/{processInstanceId}/variables
Sample URLhttps://localhost:9445/bpmn/runtime/process-instances/27503/variables
Details

This request will retrieve all the variables associated with the process instances.

Success Response Body
[
   {
      "name":"intProcVar",
      "type":"integer",
      "value":123,
      "scope":"local"
   },
   {
      "name":"byteArrayProcVar",
      "type":"binary",
      "value":null,
      "valueUrl":"https://localhost:9445/bpmn/runtime/process-instances/5/variables/byteArrayProcVar/data",
      "scope":"local"
   }
]
Get the value of a Variable of a Process Instance
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/process-instances/{processInstanceId}/variables/{variableName}
Sample URLhttps://localhost:9445/bpmn/runtime/process-instances/27503/variables/intProcVar
Details

This request is used to retrieve the value of a variable in the process instance. If it is a plain variable, the value is present in the response. Note that only local scoped variables are returned, as there is no global scope for process-instance variables.

Success Response Body
{
      "name":"intProcVar",
      "type":"integer",
      "value":123,
      "scope":"local"
}

Tasks

This represents a task, which could be a user task, service task or other tasks provided.

List all Tasks
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/tasks
Sample URLhttps://localhost:9445/bpmn/runtime/tasks
Details

This request will retrieve all the tasks on the server.

Success Response Body
{
  "data": [
    {
      "assignee" : "kermit",
      "createTime" : "2015-01-17T10:17:43.902+0000",
      "delegationState" : "pending",
      "description" : "Task description",
      "dueDate" : "2015-01-17T10:17:43.902+0000",
      "execution" : "https://localhost:9445/bpmn/runtime/executions/5",
      "id" : "8",
      "name" : "My task",
      "owner" : "owner",
      "parentTask" : "https://localhost:9445/bpmn/runtime/tasks/9",
      "priority" : 50,
      "processDefinition" : "https://localhost:9445/bpmn/repository/process-definitions/bpmnTaskProcess%3A1%3A4",
      "processInstance" : "https://localhost:9445/bpmn/runtime/process-instances/5",
      "suspended" : false,
      "taskDefinitionKey" : "theTask",
      "url" : "https://localhost:9445/bpmn/runtime/tasks/8",
      "tenantId" : null
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "name",
  "order": "asc",
  "size": 1
}
Get a Task
Request TypeGET
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}
Sample URLhttps://localhost:9445/bpmn/runtime/tasks/8
Details

This request is used to retrieve a task uniquely using the task Id.

Success Response Body
{
  "assignee" : "kermit",
  "createTime" : "2015-01-17T10:17:43.902+0000",
  "delegationState" : "pending",
  "description" : "Task description",
  "dueDate" : "2015-01-17T10:17:43.902+0000",
  "execution" : "https://localhost:9445/bpmn/runtime/executions/5",
  "id" : "8",
  "name" : "My task",
  "owner" : "owner",
  "parentTask" : "https://localhost:9445/bpmn/runtime/tasks/9",
  "priority" : 50,
  "processDefinition" : "https://localhost:9445/bpmn/repository/process-definitions/bpmnTaskProcess%3A1%3A4",
  "processInstance" : "https://localhost:9445/bpmn/runtime/process-instances/5",
  "suspended" : false,
  "taskDefinitionKey" : "theTask",
  "url" : "https://localhost:9445/bpmn/runtime/tasks/8",
  "tenantId" : null
}
Query for Task
Request TypePOST
Request URL https://<Host Name>:<Port>/bpmn/query/tasks
Sample URLhttps://localhost:9445/bpmn/query/tasks
Details

This request is used to query for a task, the query can be executed for any of the attributes of a task. Please check the response body for the attributes.

Sample Request Body
{
  "name" : "My task",
  "assignee": "kermit",
  "priority": 50
}
Success Response Body
{
  "data": [
    {
      "assignee" : "kermit",
      "createTime" : "2015-01-17T10:17:43.902+0000",
      "delegationState" : "pending",
      "description" : "Task description",
      "dueDate" : "2015-01-17T10:17:43.902+0000",
      "execution" : "https://localhost:9445/bpmn/runtime/executions/5",
      "id" : "8",
      "name" : "My task",
      "owner" : "owner",
      "parentTask" : "https://localhost:9445/bpmn/runtime/tasks/9",
      "priority" : 50,
      "processDefinition" : "https://localhost:9445/bpmn/repository/process-definitions/bpmnTaskProcess%3A1%3A4",
      "processInstance" : "https://localhost:9445/bpmn/runtime/process-instances/5",
      "suspended" : false,
      "taskDefinitionKey" : "theTask",
      "url" : "https://localhost:9445/bpmn/runtime/tasks/8",
      "tenantId" : null
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "name",
  "order": "asc",
  "size": 1
}
Update a Task
Request TypePUT
Request URL https://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}
Details

This request can be used to update any of the attributes of the task. All request values are optional. For example, you can only include the assignee attribute in the request body JSON-object, only updating the assignee of the task, leaving all other fields unaffected. When an attribute is explicitly included and is set to null, the task-value will be updated to null. For example, {"dueDate" : null} will clear the due date of the task.

Not all fields have to be sent when a request is sent as the fields are optional.

Request Body
{
  "assignee" : "assignee",
  "delegationState" : "resolved",
  "description" : "New task description",
  "dueDate" : "2015-01-17T13:06:02.438+02:00",
  "name" : "New task name",
  "owner" : "owner",
  "parentTaskId" : "3",
  "priority" : 20
}
Complete a Task
Request TypePOST
Request URL https://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}
Details

This request can be used to complete a task.

Request Body
{
  "action" : "complete"
}
Claim a Task
Request TypePOST
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}
Details

This request can be used to claim a task. You can claim a task only if there is no assignee or it has been assigned to a candidate group and you are a part of that group.

Request Body
{
  "action" : "claim",
  "assignee" : "userWhoClaims"
}
Delegate a Task
Request TypePOST
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}
Details

This request can be used to delegate a task.

Request Body
{
  "action" : "delegate",
  "assignee" : "userToDelegateTo"
}
Resolve a Task
Request TypePOST
Request URLhttps://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}
Details

This request can be used to resolve a task.

Request Body
{
  "action" : "resolve"
}
Delete a Task
Request TypeDELETE
Request URL https://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}?cascadeHistory={cascadeHistory}&deleteReason={deleteReason}
Details

This request is used to delete a task. A task can be deleted only if its not a part of a workflow or if it is in the resolved or completed state. The request is compiled of the taskId, which is the ID of the task to be deleted, cascadeHistory is a boolean value that is used to indicate whether or not to delete the HistoricTask instance when deleting the task (if applicable). If not provided, this value defaults to false. Delete reason is the reason why the task is deleted. This value is ignored when cascadeHistory is true.

There is no response body provided when you delete a Task, but the service status “204” indicates the task was found and deleted. A service status of “404” indicates the deployment was not found.

Comment on a Task
Request TypePOST
Request URL https://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}/comments
Details

This request is used to add a comment to the task.

Parameter saveProcessInstanceId is optional. If true, this saves the process instance id of the task with the comment.

Request Body
{
  "message" : "This is a comment on the task.",
  "saveProcessInstanceId" : true
}
Success Response Body
{
  "id" : "123",
  "taskUrl" : "https://localhost:9445/bpmn/runtime/tasks/101/comments/123",
  "processInstanceUrl" : "https://localhost:9445/bpmn/history/historic-process-instances/100/comments/123",
  "message" : "This is a comment on the task.",
  "author" : "kermit",
  "time" : "2015-0-13T13:13:52.232+08:00"
  "taskId" : "101",1
  "processInstanceId" : "100"
}
Get all comments on a Task
Request TypeGET
Request URL https://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}/comments
Sample URL https://localhost:9445/bpmn/runtime/tasks/8/comments
Details

This request is used to retrieve all the comments in a task.

Request Body
[
  {
    "id" : "123",
    "taskUrl" : "https://localhost:9445/bpmn/runtime/tasks/101/comments/123",
    "processInstanceUrl" : "https://localhost:9445/bpmn/history/historic-process-instances/100/comments/123",
    "message" : "This is a comment on the task.",
    "author" : "kermit"
    "time" : "2015-01-13T13:13:52.232+08:00"
    "taskId" : "101",
    "processInstanceId" : "100"
  },
  {
    "id" : "456",
    "taskUrl" : "https://localhost:9445/bpmn/runtime/tasks/101/comments/456",
    "processInstanceUrl" : "https://localhost:9445/bpmn/history/historic-process-instances/100/comments/456",
    "message" : "This is another comment on the task.",
    "author" : "gonzo",
    "time" : "2015-01-13T13:13:52.232+08:00"
    "taskId" : "101",
    "processInstanceId" : "100"
  }
]
Get a comment on a task
Request TypeGET
Request URL https://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}/comments/{commentId}
Sample URL https://localhost:9445/bpmn/runtime/tasks/8/comments/123
Details

This request is used to get a specific comment on a specific task.

Success Response Body
{
  "id" : "123",
  "taskUrl" : "https://localhost:9445/bpmn/runtime/tasks/101/comments/123",
  "processInstanceUrl" : "https://localhost:9445/bpmn/history/historic-process-instances/100/comments/123",
  "message" : "This is a comment on the task.",
  "author" : "kermit",
  "time" : "2015-01-13T13:13:52.232+08:00"
  "taskId" : "101"
  "processInstanceId" : "100"
}
Delete a comment on a task
Request TypeDELETE
Request URL https://<Host Name>:<Port>/bpmn/runtime/tasks/{taskId}/comments/{commentId}
Sample URL https://localhost:9445/bpmn/tasks/8/comments/123
Details

This request is used to delete a specific comment on a task. There is no response body provided when you delete a comment on a task, but the service status “204” indicates the comment was found and deleted. A service status of “404” indicates the deployment was not found.