REST API

The goal of the REST API is to provide access to all relevant interfaces of the engine.

Structure

These documents explain all existing methods in the REST API. For each method they provide:

• An informal description
• HTTP verb and URL
• Possible query, path or message body parameters
• A detailed description of the response content
• Possible response codes
• A brief example request and response

Engine Usage

The methods as described work on the default process engine as given by the available ProcessEngineProvider service.

You may prepend /engine/{name} to any of the methods (unless otherwise documented) to access another engine. name is the name of the process engine as returned by ProcessEngine#getName().

Error Handling

For every method this documentation gives possible HTTP status codes. The error code explanations do not cover all possible error causes that may arise when the request is served. For example, most of the requests will not work properly if there are problems with database access. Any of these undocumented errors will be translated to a HTTP 500 error.

All errors also provide a JSON response body of the form {"type" : "SomeExceptionClass", "message" : "a detailed message"}.

Authorization Exceptions

If an already authenticated user interacts with a resource in an unauthorized way, the status code of the response will be set to 403, Forbidden and details about the unauthorized interaction are provided in the response body:

{"type" : "AuthorizationException", 
 "message" : "The user with id 'jonny' does not have 'DELETE' permission on resource 'Mary' of type 'User'.",
 "userId" : "jonny",
 "permissionName" : "DELETE",
 "resourceName" : "User",
 "resourceId" : "Mary"}

Authentication

The REST API ships with an implementation of Http Basic Authentication. By default it is switched off (in the rest-api web application and therefore also in the pre-built camunda BPM distributions). You can activate it by adding a servlet filter as described in the Authentication section.

The REST API ships with an implementation of Http Basic Authentication. By default it is switched off, but can be activated by adding a servlet filter as follows:

<filter>
  <filter-name>camunda-auth</filter-name>
  <filter-class>
    org.camunda.bpm.engine.rest.security.auth.ProcessEngineAuthenticationFilter
  </filter-class>
  <init-param>
    <param-name>authentication-provider</param-name>
    <param-value>org.camunda.bpm.engine.rest.security.auth.impl.HttpBasicAuthenticationProvider</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>camunda-auth</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Any engine-specific request will then be authenticated against that engine's identity service. The GET /engine request that supplies a list of all available process engines is the only request that does not require authentication. Any request that does not address a specific engine (i.e. it is not of the form /engine/{name}/...) will be authenticated against the default engine.

In the pre-built distributions, the engine authentication is switched off by default. You may have a look at the distribution's web.xml file and remove the comment markers from the above mentioned filter declaration to activate authentication.

Note that Http Basic Authentication does not provide encryption and should be secured by an SSL connection.

The authentication provider is exchangeable. You can implement the interface org.camunda.bpm.engine.rest.security.auth.AuthenticationProvider to provide another authentication method and change the filter's initialization parameter accordingly.

Resteasy Specifics

The authentication filter works fine whenever the JAX-RS application containing the REST API is deployed as a servlet. This is not necessarily the case. One such case we are aware of is with some types of Resteasy deployments:

Resteasy allows to deploy a JAX-RS application as a servlet filter (see the Resteasy docs). If you choose this method to deploy the REST API application, which we also do in the Tomcat distro, the authentication filter requires an extra init-param named rest-url-pattern-prefix. The value has to correspond to the servlet path (see HttpServletRequest#getServletPath()) as in the case that the JAX-RS application are deployed as a servlet.

Example: If the Resteasy configuration is

<filter>
  <filter-name>Resteasy</filter-name>
  <filter-class>
      org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
  </filter-class>
  <init-param>
      <param-name>javax.ws.rs.Application</param-name>
      <param-value>org.camunda.bpm.engine.rest.impl.application.DefaultApplication</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>Resteasy</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

the following init-param has to be set:

<init-param>
  <param-name>rest-url-pattern-prefix</param-name>
  <param-value></param-value>
</init-param>

In the example above the value is empty, because the Resteasy filter mapping is /\* and a servlet with that mapping would have an empty servlet path. Similarly, the filter mapping url /rest/\* maps to the init-param /rest and so on.

The REST API is included in camunda's pre-built distributions. It may be accessed via the context /engine-rest and uses the engines provided by the class BpmPlatform.

The default process engine is available out of the box by accessing /engine-rest/engine/default/{rest-methods} or simply /engine-rest/{rest-methods}. Any other shared process engine, i.e. it is globally visible, that is created later is available through /engine-rest/engine/{name}/{rest-methods} without any further configuration.

Authentication is deactivated by default, but can be activated as described in the authentication section.

The REST API is an artifact of its own, which means that it can be embedded in any other JAX-RS application independently of the engine.

Prerequisites

The REST API classes are tested with Resteasy, Jersey and Wink as the JAX-RS implementation. Furthermore the engine classes and Jackson's org.codehaus.jackson:jackson-jaxrs artifact have to be on the classpath.

Required steps

• Add the REST API as a Maven dependency to your project.

  <dependency>
    <groupId>org.camunda.bpm</groupId>
    <artifactId>camunda-engine-rest</artifactId>
    <classifier>classes</classifier>
    <version>7.0.0-Final</version>
  </dependency>

• Add those REST resources to your JAX-RS application that you need. Example:

  @ApplicationPath("/")
  public class MyApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
      Set<Class<?>> classes = new HashSet<Class<?>>();
      // add your own classes 
      ...
      // add all camunda engine rest resources (Or just add those that you actually need).
      classes.addAll(CamundaRestResources.getResourceClasses());
  
      // mandatory
      classes.addAll(CamundaRestResources.getConfigurationClasses());
  
      return classes;
    }
  }

  The classes org.camunda.bpm.engine.rest.*RestServiceImpl classes contain the methods as structured in this documentation. ProcessEngineRestServiceImpl adds the functionality that different engines may be addressed. If it is not included the default engine will always be used and /engine/{name} URLs will not be available.

  JacksonConfigurator is required to configure the serialization of date fields correctly. You may also have to add the following Jackson providers: org.codehaus.jackson.jaxrs.JacksonJsonProvider, org.codehaus.jackson.jaxrs.JsonMappingExceptionMapper and org.codehaus.jackson.jaxrs.JsonParseExceptionMapper. Depending on the runtime environment, this may not be necessary. On JBoss AS 7 these should be automatically added as an implicit module dependency.

  For proper exception responses of the format as described in the Introduction, it is required to include RestExceptionHandler. ProcessEngineExceptionHandler is used to translate any exception thrown by the engine that is not explicitly handled by the REST API classes to a generic HTTP 500 error with the same response body format. If you would like to have all kinds of exceptions translated to this format, you can use org.camunda.bpm.engine.rest.exception.ExceptionHandler instead of ProcessEngineExceptionHandler.

  Next is the wiring of the REST API and the process engine(s). This requires to create a Service Provider that implements the interface ProcessEngineProvider and declare it in a file META-INF/services/org.camunda.bpm.engine.rest.spi.ProcessEngineProvider. You may also declare the class org.camunda.bpm.engine.rest.impl.application.ContainerManagedProcessEngineProvider which comes with the REST API and uses the methods the class org.camunda.bpm.BpmPlatform provides.

Deletes an authorization by id.

Method

DELETE /authorization/{id}

Parameters

Path Parameters

Request Body

Empty.

Result

This method returns no content.

Response codes

Example

Request

DELETE /authorization/anAuthorizationId

Response

Status 204. No content.

Retrieves a single authorization by Id.

Method

GET /authorization/{id}

Parameters

Path Parameters

Result

A json array with the following properties:

Response codes

Example

Request

GET /authorization/anAuthorizationId

Response

Status 200.

{"id":"anAuthorizationId",
 "type": 0,
 "permissions": ["CREATE", "READ"],
 "userId": "*",
 "groupId": null,
 "resourceType": 1,
 "resourceId": "*"}

Performs an authorization check for the currently authenticated user.

Method

GET /authorization/check

Parameters

Query Parameters

Result

A json array with the following properties:

Response codes

Example

Request

GET /authorization/check?permissionName=READ,permissionValue=2,resourceName=USER,resourceType=1,resourceId=jonny

Response

Status 200.

{"permissionName": "READ",
 "resourceName": "USER",
 "resourceId": "jonny",
 "isAuthorized": true}

Query for a list of authorizations using a list of parameters. The size of the result set can be retrieved by using the get authorization count method.

Method

GET /authorization

Parameters

Query Parameters

Result

A json array of authorization objects. Each group object has the following properties:

Response codes

Example

Request

GET /authorization?userIdIn=jonny1,jonny2

Response

Status 200.

[{"id":"anAuthorizationId",
 "type": 0,
 "permissions": ["ALL"],
 "userId": "jonny1",
 "groupId": null,
 "resourceType": 1,
 "resourceId": "*"},
 {"id":"anotherAuthorizationId",
 "type": 0,
 "permissions": ["CREATE", "READ"],
 "userId": "jonny2",
 "groupId": null,
 "resourceType": 1,
 "resourceId": "*"}]

Query for authorizations using a list of parameters and retrieves the count.

Method

GET /authorization/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /authorization/count?userIdIn=jonny1,jonny2

Response

Status 200.

{"count": 2}

The /authorization resource supports two custom OPTIONS requests, one for the resource as such and one for individual authorization instances. The options request allows checking for the set of available operations that the currently authenticated user can perform on the /authorization resource. The fact whether the user can perform an operation may depend on various things, including the users authorizations to interact with this resource and the interal configuration of the process engine.

Method

OPTIONS /authorization for available interactions on resource OPTIONS /authorization/{id} for available interactions on resource instance

Result

A Json object with a single property named links, providing a list of resource links. Each link has the following properties

Response codes

Example

Request

OPTIONS /authorization/anAuthorizationId

Response

Status 200.

{"links":[
  {"method": "GET", href":"http://localhost:8080/engine-rest/authorization/anAuthorizationId", "rel":"self"},
  {"method": "PUT", href":"http://localhost:8080/engine-rest/authorization/anAuthorizationId", "rel":"update"},
  {"method": "DELETE", href":"http://localhost:8080/engine-rest/authorization/anAuthorizationId", "rel":"delete"}]}

Creates a new authorization

Method

POST /authorization/create

Parameters

Request Body

A json object with the following properties:

Result

A json array with the following properties:

Response codes

Example

Request

POST /authorization/create

Request body:

{"type" : 0,
 "permissions": ["CREATE", "READ"],
 "userId": "*",
 "groupId": null,
 "resourceType": 1,
 "resourceId": "*"}

Response

Status 200.

{"id":"anAuthorizationId",
 "type": 0,
 "permissions": ["CREATE", "READ"],
 "userId": "*",
 "groupId": null,
 "resourceType": 1,
 "resourceId": "*",
 "links":[
    {"method": "GET", href":"http://localhost:8080/engine-rest/authorization/anAuthorizationId", "rel":"self"},
    {"method": "PUT", href":"http://localhost:8080/engine-rest/authorization/anAuthorizationId", "rel":"update"},
    {"method": "DELETE", href":"http://localhost:8080/engine-rest/authorization/anAuthorizationId", "rel":"delete"}
  ]}

Updates a single authorization.

Method

PUT /authorization/{id}

Parameters

Path Parameters

Request Body

A json object with the following properties:

Result

Empty.

Response codes

Example

Request

PUT /authorization/anAuthorizationId

Request body:

{"permissions": 16,
 "userId": "*",
 "groupId": null,
 "resourceType": 1,
 "resourceId": "*"}

Response

Empty.

Retrieves the names of all process engines available on your platform.

Note: You cannot prepend /engine/{name} to this method.

Method

GET /engine

Parameters

This method takes no parameters.

Result

A json array consisting of engine objects. Each engine object has the following properties:

Response codes

Example

Request

GET /engine

Response

[{"name":"default"},
 {"name":"anotherEngineName"}]

Deletes a variable in the context of a given execution. Deletion does not propagate upwards in the execution hierarchy.

Method

DELETE /execution/{id}/localVariables/{varId}

Parameters

Path Parameters

Result

This method returns no content.

Response codes

Example

Request

DELETE /execution/anExecutionId/localVariables/aVarName

Response

Status 204. No content.

Retrieves a single execution according to the Execution interface in the engine.

Method

GET /execution/{id}

Parameters

Path Parameters

Result

A json object corresponding to the Execution interface in the engine. Its properties are as follows:

Response codes

Example

Request

GET /execution/anExecutionId

Response

{"id":"anExecutionId",
"processInstanceId":"aProcInstId",
"ended":false}

Retrieves a variable from the context of a given execution. Does not traverse the parent execution hierarchy.

Method

GET /execution/{id}/localVariables/{varId}

Parameters

Path Parameters

Result

A json object with the following properties:

Response codes

Example

Request

GET /execution/anExecutionId/localVariables/aVarName

Response

{"value" : "someValue",
 "type" : "String"}

Retrieves all variables of a given execution.

Method

GET /execution/{id}/localVariables

Parameters

Path Parameters

Result

A json object of variables key-value pairs. Each key is a variable name and each value a variable value object that has the following properties:

Response codes

Example

Request

GET /execution/anExecutionId/localVariables

Response

{"anExecutionVariableKey":
  {"value":
    {"property1":"aPropertyValue",
    "property2":true},
  "type":"ExampleVariableObject"}}

Get a message event subscription for a specific execution and a message name.

Method

GET /execution/{id}/messageSubscriptions/{messageName}

Parameters

Path Parameters

Result

A json object with the following properties:

Response codes

Example

Request

GET /execution/anExecutionId/messageSubscriptions/someMessage

Response

{"id": "anEventSubscriptionId",
"eventType": "message",
"eventName": "anEvent",
"executionId": "anExecutionId",
"processInstanceId": "aProcInstId",
"activityId": "anActivity",
"createdDate": "2013-01-23T13:59:43"}

Query for the number of executions that fulfill given parameters. Parameters may be static as well as dynamic runtime properties of executions. The size of the result set can be retrieved by using the get executions count method.

Method

GET /execution

Parameters

Query Parameters

Result

A json array of execution objects. Each execution object has the following properties:

Response codes

Example

Request

GET /execution?variables=myVariable_eq_camunda

Response

Status 200.

[{"id":"anId",
 "processInstanceId":"aProcInstId",
 "ended":false}]

Query for the number of executions that fulfill given parameters. Takes the same parameters as the get executions method.

Method

GET /execution/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /execution/count?variables=myVariable_eq_camunda

Response

{"count": 1}

Updates or deletes the variables in the context of an execution. The updates do not propagate upwards in the execution hierarchy. Updates precede deletes. So if a variable is updated AND deleted, the deletion overrides the update.

Method

POST /execution/{id}/localVariables

Parameters

Path Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /execution/anExecutionId/localVariables

Request body:

{"modifications": 
    {"aVariable": {"value": "aValue", "type": "String"},
    "anotherVariable": {"value": 42, "type": "Integer"}},
"deletions": [
    "aThirdVariable", "FourthVariable"
]}

Response

Status 204. No content.

Deliver a message to a specific execution to trigger an existing message event subscription. Inject process variables as the message's payload.

Method

POST /execution/{id}/messageSubscriptions/{messageName}/trigger

Parameters

Path Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /execution/anExecutionId/messageSubscriptions/someMessage/trigger

Request body:

{"variables" :
    {"aVariable" : {"value" : true, "type": "Boolean"},
     "anotherVariable" : {"value" : 42, "type": "Integer"}}
}

Response

Status 204. No content.

Query for executions that fulfill given parameters through a json object. This method is slightly more powerful than the GET query, because it allows to filter by multiple instance and execution variables of types String, Number or Boolean.

Method

POST /execution

Parameters

Query Parameters

Request Body

A json object with the following properties:

Result

A json array of execution objects. Each execution object has the following properties:

Response codes

Example

Request

POST /execution

Request body:

{"variables": 
    [{"name": "myVariable",
     "operator": "eq",
     "value": "camunda"
    },
    {"name": "mySecondVariable",
     "operator": "neq",
     "value": 124}],
"processDefinitionId":"aProcessDefinitionId"}

Response

Status 200.

[{"id":"anId",
 "processInstanceId":"aProcInstId",
 "ended":false}]

Query for the number of executions that fulfill given parameters. This method takes the same message body as the POST query and is thus slightly more powerful than the GET query count api.

Method

POST /process-instance/count

Parameters

Request Body

A json object with the following properties:

Result

A json object that contains the count as the only property.

Response codes

Example

Request

POST /execution/count

Request body:

{"variables": 
    [{"name": "myVariable",
     "operator": "eq",
     "value": "camunda"
    },
    {"name": "mySecondVariable",
     "operator": "neq",
     "value": 124}],
"processDefinitionId":"aProcessDefinitionId"}

Response

{"count": 1}

Signals a single execution. Can for example be used to explicitly skip user tasks or signal asynchronous continuations.

Method

POST /execution/{id}/signal

Parameters

Path Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /execution/{id}/signal

Request body:

{"variables": 
    {"myVariable": {"value": "camunda", "type": "String"},
    "mySecondVariable": {"value": 124, "type": "Integer"}}
}

Response

Status 204. No content.

Sets a variable in the context of a given execution. Update does not propagate upwards in the execution hierarchy.

Method

PUT /execution/{id}/localVariables/{varId}

Parameters

Path Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

PUT /execution/anExecutionId/localVariables/aVarName

{"value" : "someValue", "type": "String"}

Response

Status 204. No content.

Sets the value for a binary variable

Method

POST /execution/{id}/localVariables/{varId}/data

Parameters

Path Parameters

Request Body

A multipart form submit with the following parts:

Result

This method returns no content.

Response codes

Example

Request

(1) Post the json serialization of a Java Class:

POST /execution/anExecutionId/localVariables/aVarName/data

---OSQH1f8lzs83iXFHphqfIuitaQfNKFY74Y
Content-Disposition: form-data; name="data"
Content-Type: application/json; charset=US-ASCII
Content-Transfer-Encoding: 8bit

["foo", "bar"]
---OSQH1f8lzs83iXFHphqfIuitaQfNKFY74Y
Content-Disposition: form-data; name="type"
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit

java.util.ArrayList<java.lang.Object>
---OSQH1f8lzs83iXFHphqfIuitaQfNKFY74Y--

(2) Post binary content of a byte array variable:

POST /execution/anExecutionId/localVariables/aVarName/data

---OSQH1f8lzs83iXFHphqfIuitaQfNKFY74Y
Content-Disposition: form-data; name="data"; filename="unspecified"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

<<Byte Stream ommitted>>
---OSQH1f8lzs83iXFHphqfIuitaQfNKFY74Y--

Deletes a group by id.

Method

DELETE /group/{id}

Parameters

Path Parameters

Request Body

Empty.

Result

This method returns no content.

Response codes

Example

Request

DELETE /group/sales

Response

Status 204. No content.

Retrieves a single group.

Method

GET /group/{id}

Parameters

Path Parameters

Result

A json array of group objects. Each group object has the following properties:

Response codes

Example

Request

GET /group/sales

Response

Status 200.

{"id":"sales",
 "name":"Sales",
 "type":"Organizational Unit"}

Query for a list of groups using a list of parameters. The size of the result set can be retrieved by using the get groups count method.

Method

GET /group

Parameters

Query Parameters

Result

A json array of group objects. Each group object has the following properties:

Response codes

Example

Request

GET /group?name=Sales

Response

Status 200.

[{"id":"sales",
  "name":"Sales",
  "type":"Organizational Unit"}]

Query for groups using a list of parameters and retrieves the count.

Method

GET /group/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /group/count?name=Sales

Response

Status 200.

{"count": 1}

Removes a member from a group.

Method

DELETE /group/{id}/members/{userId}

Parameters

Path Parameters

Request Body

Empty.

Result

This method returns no content.

Response codes

Example

Request

DELETE /group/sales/members/jonny1

Response

Status 204. No content.

Add a member to a group.

Method

PUT /group/{id}/members/{userId}

Parameters

Request Body

None.

Result

None.

Response codes

Example

Request

PUT /group/sales/members/jonny1

Request body:

Empty.

Response

None.

The /group resource supports two custom OPTIONS requests, one for the resource as such and one for individual group instances. The options request allows checking for the set of available operations that the currently authenticated user can perform on the /group resource. The fact whether the user can perform an operation may depend on various things, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Method

OPTIONS /group for available interactions on resource OPTIONS /group/{id} for available interactions on resource instance

Result

A Json object with a single property named links, providing a list of resource links. Each link has the following properties

Response codes

Example 1

Request

OPTIONS /group

Response

Status 200.

{"links":[
    {"method":"GET","href":"http://localhost:8080/camunda/api/engine/engine/default/group","rel":"list"},
    {"method":"GET","href":"http://localhost:8080/camunda/api/engine/engine/default/group/count","rel":"count"},
    {"method":"POST","href":"http://localhost:8080/camunda/api/engine/engine/default/group/create","rel":"create"}]}

Example 2

Request

OPTIONS /group/aGroupId

Response

Status 200.

{"links":[
    {"method":"GET","href":"http://localhost:8080/camunda/api/engine/engine/default/group/aGroupId","rel":"self"},
    {"method":"DELETE","href":"http://localhost:8080/camunda/api/engine/engine/default/group/aGroupId","rel":"delete"},
    {"method":"PUT","href":"http://localhost:8080/camunda/api/engine/engine/default/group/aGroupId","rel":"update"}]}

Create a new group.

Method

POST /group/create

Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /group/create

Request body:

{"id":"sales",
 "name":"Sales",
 "type":"Organizational Unit"}

Response

Status 204. No content.

Updates a given group.

Method

PUT /group/{id}

Parameters

Path Parameters

Request Body

A json object with the following properties:

Result

Empty.

Response codes

Example

Request

PUT /group/sales

Request body:

{"id":"sales",
 "name":"Sales",
 "type":"Organizational Unit"}

Response

Empty.

Query for historic activity instances that fulfill the given parameters. The size of the result set can be retrieved by using the count method.

Method

GET /history/activity-instance

Parameters

Query Parameters

Result

A json array of historic activity instance objects. Each historic activity instance object has the following properties:

Response codes

Example

Request

GET /history/activity-instance?activityType=userTask&taskAssignee=peter

Response

[{"id": "aHistoricActivityInstanceId",
"parentActivityInstanceId": "aHistoricParentActivityInstanceId",
"activityId": "anActivity",
"activityName": "anActivityName",
"activityType": "userTask",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anExecutionId",
"taskId": "aTaskId",
"calledProcessInstanceId": "aHistoricCalledProcessInstanceId",
"assignee": "peter",
"startTime": "2013-04-23T11:20:43",
"endTime": "2013-04-23T18:42:43",
"durationInMillis": 2000
"canceled": true,
"completeScope": false}]

Query for the number of historic activity instances that fulfill the given parameters. Takes the same parameters as the get historic activity instances method.

Method

GET /history/activity-instance/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /history/activity-instance/count?activityType=userTask

Response

{"count": 1}

Retrieves a single historic detail by id.

Method

GET /history/detail/{id}

Parameters

Path Parameters

Result

An object having the following properties:

Depending on the concrete instance of the historic detail it contains further properties. In case of an HistoricVariableUpdate the following properties are also provided:

In case of an HistoricFormField the following properties are also provided:

Response codes

Example

Request

GET /history/detail/someId

Response

Status 200.

{
  "id": "12345",
  "processInstanceId": "aProcInstId",
  "activityInstanceId": "anActInstId",
  "executionId": "anExecutionId",
  "time": "2014-02-28T15:00:00",
  "variableName": "myProcessVariable",
  "variableInstanceId": "aVariableInstanceId",
  "variableTypeName": "String",
  "value": "aVariableValue",
  "revision": 1,
  "errorMessage": null
}

Retrieves the binary content of a single historic detail variable update by id.

Method

GET /history/detail/{id}/data

Parameters

Path Parameters

Result

Byte stream.

Response codes

Example

Request

GET /history/detail/someId/data

Response

Status 200.

Byte Stream.

Query for historic details that fulfill the given parameters. The size of the result set can be retrieved by using the count method.

Method

GET /history/detail

Parameters

Query Parameters

Result

A json array of historic detail objects. Each historic detail object has the following properties:

Depending on the concrete instance of the historic detail it contains further properties. In case of an HistoricVariableUpdate the following properties are also provided:

In case of an HistoricFormField the following properties are also provided:

Response codes

Example

Request

GET /history/detail?processInstanceId=aProcInstId

Response

[
  {
    "id": "12345",
    "processInstanceId": "aProcInstId",
    "activityInstanceId": "anActInstId",
    "executionId": "anExecutionId",
    "time": "2014-02-28T15:00:00",
    "variableName": "myProcessVariable",
    "variableInstanceId": "aVariableInstanceId",
    "variableTypeName": "String",
    "value": "aVariableValue",
    "revision": 1,
    "errorMessage": null
  },
  {
    "id": "12345",
    "processInstanceId": "aProcInstId",
    "activityInstanceId": "anActInstId",
    "executionId": "anExecutionId",
    "taskId": "aTaskId",
    "time": "2014-02-28T15:00:00",
    "fieldId": "aFieldId",
    "fieldValue": "aFieldValue"
  }
]

Query for the number of historic details that fulfill the given parameters. Takes the same parameters as the get historic details method.

Method

GET /history/detail/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /history/detail/count?variableName=my_variable

Response

{"count": 3}

Retrieves historic statistics of a given process definition grouped by activities. These statistics include the number of running activity instances, optionally the number of canceled activity instances, finished activity instances and also optionally the number of activity instances, which completed a scope (ie. in BPMN 2.0 manner: a scope is completed by an activity instance, when the activity instance consumed a token but did not emit a new token).
Note: This only include historic data.

Method

GET /history/process-definition/{id}/statistics

Parameters

Path Parameters

Query Parameters

Result

A json array containing statistics results per activity. Each object has the following properties:

Response codes

Examples

Request with query parameter canceled=true

GET history/process-definition/aProcessDefinitionId/statistics?canceled=true

Response

[
  {
    "id": "anActivity",
    "instances": 123,
    "canceled": 50,
    "finished": 0,
    "completeScope": 0
  },
  {
    "id":"anotherActivity",
    "instances": 200,
    "canceled": 150,
    "finished": 0,
    "completeScope": 0
  }
]

Request with query parameter finished=true

GET history/process-definition/aProcessDefinitionId/statistics?finished=true

Response

[
  {
    "id": "anActivity",
    "instances": 123,
    "canceled": 0,
    "finished": 20,
    "completeScope": 0
  },
  {
    "id":"anotherActivity",
    "instances": 200,
    "canceled": 0,
    "finished": 30,
    "completeScope": 0
  }
]

Request with query parameter completeScope=true

GET history/process-definition/aProcessDefinitionId/statistics?completeScope=true

Response

[
  {
    "id": "anActivity",
    "instances": 123,
    "canceled": 0,
    "finished": 0,
    "completeScope": 20
  },
  {
    "id":"anotherActivity",
    "instances": 200,
    "canceled": 0,
    "finished": 0,
    "completeScope": 1
  }
]

Query for historic incidents that fulfill given parameters. The size of the result set can be retrieved by using the get incidents count method.

Method

GET /history/incident

Parameters

Query Parameters

Result

A json array of historic incident objects. Each historic incident object has the following properties:

Response codes

Example

Request

GET /history/incident?processInstanceId=aProcInstId

Response

[
  {
    "id": "anIncidentId",
    "processDefinitionId": "aProcDefId",
    "processInstanceId": "aProcInstId",
    "executionId": "anExecutionId",
    "createTime": "2014-03-01T08:00:00",
    "endTime": null,
    "incidentType": "failedJob",
    "activityId": "serviceTask",
    "causeIncidentId": "aCauseIncidentId",
    "rootCauseIncidentId": "aRootCauseIncidentId",
    "configuration": "aConfiguration",
    "incidentMessage": "anIncidentMessage",
    "open": true,
    "deleted": false,
    "resolved": false
  },
  {
    "id": "anIncidentId",
    "processDefinitionId": "aProcDefId",
    "processInstanceId": "aProcInstId",
    "executionId": "anotherExecutionId",
    "createTime": "2014-03-01T08:00:00",
    "endTime": "2014-03-10T12:00:00",
    "incidentType": "customIncidentType",
    "activityId": "userTask",
    "causeIncidentId": "anotherCauseIncidentId",
    "rootCauseIncidentId": "anotherRootCauseIncidentId",
    "configuration": "anotherConfiguration",
    "incidentMessage": "anotherIncidentMessage",
    "open": false,
    "deleted": false,
    "resolved": true
  }
]

Query for the number of historic incidents that fulfill the given parameters. Takes the same parameters as the get incidents method.

Method

GET /history/incident/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /history/incident/count?processInstanceId=aProcInstId

Response

{"count": 2}

Retrieves a single historic process instance according to the HistoricProcessInstance interface in the engine.

Method

GET /history/process-instance/{id}

Parameters

Path Parameters

Result

A json object corresponding to the HistoricProcessInstance interface in the engine. Its properties are as follows:

Response codes

Example

Request

GET /history/process-instance/aProcInstId

Response

{
  "id": "aProcInstId",
  "businessKey": "aKey",
  "processDefinitionId": "aProcDefId",
  "startTime": "2013-03-23T13:42:43",
  "endTime": "2013-03-23T13:42:45",
  "durationInMillis": 2000,
  "startUserId": "aStartUserId",
  "startActivityId": "aStartActivityId",
  "deleteReason": "aDeleteReason",
  "superProcessInstanceId": "aSuperProcessInstanceId"
}

Query for historic process instances that fulfill the given parameters. The size of the result set can be retrieved by using the get historic process instances count method.

Method

GET /history/process-instance

Parameters

Query Parameters

Result

A json array of historic process instance objects. Each historic process instance object has the following properties:

Response codes

Example

Request

GET /history/process-instance?finishedAfter=2013-01-01T00:00:00&finishedBefore=2013-04-01T23:59:59

Response

[{"id": "aProcInstId",
"businessKey": "aKey",
"processDefinitionId": "aProcDefId",
"startTime": "2013-03-23T13:42:43",
"endTime": "2013-03-23T13:42:45",
"durationInMillis": 2000,
"startUserId": "aStartUserId",
"startActivityId": "aStartActivityId",
"deleteReason": "aDeleteReason",
"superProcessInstanceId": "aSuperProcessInstanceId"}]

Query for the number of historic process instances that fulfill the given parameters. Takes the same parameters as the Get Activity Instances method.

Method

GET /history/process-instance/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /history/process-instance/count?variables=myVariable_eq_camunda

Response

{"count": 1}

Query for historic tasks that fulfill the given parameters. The size of the result set can be retrieved by using the count method.

Method

GET /history/task

Parameters

Query Parameters

Result

A json array of historic task objects. Each historic task object has the following properties:

Response codes

Example

Request

GET /history/task?taskAssignee=anAssignee&priority=42

Response

[{"id":"anId",
 "processDefinitionId":"aProcDefId",
 "processInstanceId":"aProcInstId",
 "executionId":"anExecution",
 "activityInstanceId": "anActInstId",
 "name":"aName",
 "description":"aDescription",
 "deleteReason": "aDeleteReason",
 "owner":"anOwner",
 "assignee":"anAssignee",
 "startTime":"2013-01-23T13:42:42",
 "endTime":"2013-01-23T13:45:42",
 "duration": 2000,
 "taskDefinitionKey":"aTaskDefinitionKey",
 "priority":42,
 "due":"2013-01-23T13:49:42",
 "parentTaskId":"aParentId",
 "followUp:":"2013-01-23T13:44:42"}]

Query for the number of historic tasks that fulfill the given parameters. Takes the same parameters as the get historic tasks method.

Method

GET /history/task/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /history/task/count?taskAssginee=anAssignee&taskPriority=50

Response

{"count": 1}

Query for user operation log entries that fulfill the given parameters. The size of the result set can be retrieved by using the count method.

Method

GET /history/user-operation

Parameters

Query Parameters

Result

An JSON array of user operation log entries. Each log entry has the following properties:

Response codes

Example

Request

GET /history/user-operation?operationType=Claim&userId=demo&sortBy=timestamp&sortOrder=asc

Response

[{"id": "anUserOperationLogEntryId",
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "aProcessInstanceId",
"executionId": "anExecutionId",
"taskId": "aTaskId",
"userId": "demo",
"timestamp": "2014-02-25T14:58:37",
"operationId": "anOperationId",
"operationType": "Claim",
"entityType": "Task",
"property": "assignee",
"orgValue": null,
"newValue": "demo"}]

Query for the number of user operation log entries that fulfill the given parameters. Takes the same parameters as the get log entries method.

Method

GET /history/user-operation/count

Parameters

Query Parameters

Result

An JSON object that contains the count as the only property.

Response codes

Example

Request

GET /history/user-operation?operationType=Claim&userId=demo

Response

{"count": 1}

Retrieves a single historic variable by id.

Method

GET /history/variable-instance/{id}

Parameters

Path Parameters

Result

A user object with the following properties:

Response codes

Example

Request

GET /history/variable-instance/someId

Response

Status 200.

{
  "id": "someId",
  "name": "amount",
  "type": "integer",
  "value": 5,
  "processInstanceId": "aProcessInstanceId",
  "activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726",
  "taskId": null,
  "errorMessage": null
}

Retrieves the binary content of a single historic variable by id.

Method

GET /history/variable-instance/{id}/data

Parameters

Path Parameters

Result

Byte stream.

Response codes

Example

Request

GET /history/variable-instance/someId/data

Response

Status 200.

Byte Stream.

Query for historic variable instances that fulfill the given parameters. The size of the result set can be retrieved by using the count method.

Method

GET /history/variable-instance

Parameters

Query Parameters

Result

A json array of historic variable instance objects. Each historic activity instance object has the following properties:

Response codes

Example

Request

GET /history/variable-instance?variableName=my_variable

Response

[
  {
    "id": "someId",
    "name": "my_variable",
    "type": "string",
    "value": "my_value",
    "processInstanceId": "aVariableInstanceProcInstId",
    "activityInstanceId": "aVariableInstanceActivityInstId",
    "taskId": null,
    "errorMessage": null
  }
]

Query for the number of historic variable instances that fulfill the given parameters. Takes the same parameters as the get historic variable instances method.

Method

GET /history/variable-instance/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /history/variable-instance/count?variableName=my_variable

Response

{"count": 1}

Query for historic process instances that fulfill the given parameters. This method is slightly more powerful than the GET query, because it allows to filter by multiple process variables of types String, Number or Boolean.

Method

POST /history/process-instance

Parameters

Query Parameters

Request Body

A json object with the following properties:

Result

A json array of historic process instance objects. Each historic process instance object has the following properties:

Response codes

Example

Request

POST /history/process-instance

Request body:

{"variables": 
    [{"name": "myVariable",
     "operator": "eq",
     "value": "camunda"
    },
    {"name": "mySecondVariable",
     "operator": "neq",
     "value": 124}],
"finishedAfter":"2013-01-01T00:00:00",
"finishedAfter":"2013-04-01T23:59:59"}

Response

[{"id": "aProcInstId",
"businessKey": "aKey",
"processDefinitionId": "aProcDefId",
"startTime": "2013-03-23T13:42:43",
"endTime": "2013-03-23T13:42:45",
"durationInMillis": 2000,
"startUserId": "aStartUserId",
"startActivityId": "aStartActivityId",
"deleteReason": "aDeleteReason",
"superProcessInstanceId": "aSuperProcessInstanceId"}]

Query for the number of historic process instances that fulfill the given parameters. This method takes the same message body as the POST query and is thus slightly more powerful than the GET query count.

Method

POST /history/process-instance/count

Parameters

Request Body

A json object with the following properties:

Result

A json object that contains the count as the only property.

Response codes

Example

Request

POST /history/process-instance/count

Request body:

{"variables": 
    [{"name": "myVariable",
     "operator": "eq",
     "value": "camunda"
    },
    {"name": "mySecondVariable",
     "operator": "neq",
     "value": 124}],
"finishedAfter":"2013-01-01T00:00:00",
"finishedAfter":"2013-04-01T23:59:59"}

Response

{"count": 1}

Query for historic tasks that fulfill the given parameters. This method is slightly more powerful than the GET query, because it allows to filter by multiple process or task variables of types String, Number or Boolean. The size of the result set can be retrieved by using get tasks count (POST) method.

Method

POST /history/task

Parameters

Query Parameters

Request Body

A json object with the following properties:

Result

A json array of historic task objects. Each historic task object has the following properties:

Response codes

Example

Request

POST /history/task

Request body:

{"taskVariables":
    [{"name": "varName",
    "value": "varValue",
    "operator": "eq"
    },
    {"name": "anotherVarName",
    "value": 30,
    "operator": "neq"}],
"priority":10}

Response

[{"id":"anId",
 "processDefinitionId":"aProcDefId",
 "processInstanceId":"aProcInstId",
 "executionId":"anExecution",
 "activityInstanceId": "anActInstId",
 "name":"aName",
 "description":"aDescription",
 "deleteReason": "aDeleteReason",
 "owner":"anOwner",
 "assignee":"anAssignee",
 "startTime":"2013-01-23T13:42:42",
 "endTime":"2013-01-23T13:45:42",
 "duration": 2000,
 "taskDefinitionKey":"aTaskDefinitionKey",
 "priority":10,
 "due":"2013-01-23T13:49:42",
 "parentTaskId":"aParentId",
 "followUp:":"2013-01-23T13:44:42"}]

Query for the number of historic tasks that fulfill the given parameters. Takes the same parameters as the get historic tasks method. Corresponds to the size of the result set of the get tasks (POST) method and takes the same parameters.

Method

POST /history/task/count

Parameters

Request Body

A json object with the following properties:

Result

A json object that contains the count as the only property.

Response codes

Example

Request

POST /history/task/count

Request body:

{"taskVariables":
    [{"name": "varName",
    "value": "varValue",
    "operator": "eq"
    },
    {"name": "anotherVarName",
    "value": 30,
    "operator": "neq"}],
"priority":10}

Response

{"count": 1}

Query for historic variable instances that fulfill the given parameters. This method is slightly more powerful than the GET query, because it allows to filter by variable values of the different types String, Number or Boolean.

Method

POST /history/variable-instance

Parameters

Query Parameters

Request body

A json object with the following properties:

Result

A json array of historic variable instance objects. Each historic activity instance object has the following properties:

Response codes

Example

Request

POST /history/variable-instance

Request body:

{"variableValue": 42,
"variableName":"someVariable"}

Response

[
  {
    "id": "aId",
    "name": "someVariable",
    "type": "integer",
    "value": 42,
    "processInstanceId": "aProcInstId",
    "activityInstanceId": "aActivityInstId",
    "taskId": null
  }
]

Query for historic variable instances that fulfill the given parameters. This method takes the same message body as the POST query and is thus more powerful regarding variable values than the GET query count method.

Method

POST /history/variable-instance/count

Parameters

Request body

A json object with the following properties:

Result

A json object that contains the count as the only property.

Response codes

Example

Request

POST /history/variable-instance/count

Request body:

{"variableValue": 42,
"variableName":"someVariable"}

Response

{"count" : 1}

Gets the groups of a user and all users that share a group with the given user.

Method

GET /identity/groups

Parameters

Query Parameters

Result

A json object containing groups, the number of members and other users. Its properties are as follows:

Response codes

Example

Request

GET /identity/groups?userId=aUserId

Response

{"groups":
  [{"id":"group1Id",
   "name":"group1"}],
"groupUsers":
  [{"firstName":"firstName",
   "lastName":"lastName",
   "displayName":"firstName lastName",
   "id":"anotherUserId"}]}

Query for incidents that fulfill given parameters. The size of the result set can be retrieved by using the get incidents count method.

Method

GET /incident

Parameters

Query Parameters

Result

A json array of incident objects. Each incident object has the following properties:

Response codes

Example

Request

GET /incident?processInstanceId=aProcInstId

Response

[
  {
    "id": "anIncidentId",
    "processDefinitionId": "aProcDefId",
    "processInstanceId": "aProcInstId",
    "executionId": "anExecutionId",
    "incidentTimestamp": "2014-03-01T08:00:00",
    "incidentType": "failedJob",
    "activityId": "serviceTask",
    "causeIncidentId": "aCauseIncidentId",
    "rootCauseIncidentId": "aRootCauseIncidentId",
    "configuration": "aConfiguration",
    "incidentMessage": "anIncidentMessage"
  },
  {
    "id": "anIncidentId",
    "processDefinitionId": "aProcDefId",
    "processInstanceId": "aProcInstId",
    "executionId": "anotherExecutionId",
    "incidentTimestamp": "2014-03-01T09:00:00",
    "incidentType": "customIncidentType",
    "activityId": "userTask",
    "causeIncidentId": "anotherCauseIncidentId",
    "rootCauseIncidentId": "anotherRootCauseIncidentId",
    "configuration": "anotherConfiguration",
    "incidentMessage": "anotherIncidentMessage"
  }
]

Query for the number of incidents that fulfill given parameters. Takes the same parameters as the get incidents method.

Method

GET /incident/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /incident/count?processInstanceId=aProcInstId

Response

{"count": 2}

Retrieves a single job definition according to the JobDefinition interface in the engine.

Method

GET /job-definition/{id}

Parameters

Path Parameters

Result

A json object corresponding to the JobDefinition interface in the engine. Its properties are as follows:

Response codes

Example

Request

GET /job-definition/aJobDefinitionId

Response

  {
    "id": "aJobDefId",
    "processDefinitionId": "aProcDefId",
    "processDefinitionKey": "aProcDefKey",
    "activityId": "ServiceTask1",
    "jobType": "asynchronous-continuation",
    "jobConfiguration": "",
    "suspended": false
  }

Query for job definitions that fulfill given parameters. The size of the result set can be retrieved by using the get job definitions count method.

Method

GET /job-definition

Parameters

Query Parameters

Result

A json array of job definition objects. Each job definition object has the following properties:

Response codes

Example

Request

GET /job-definition?activityIdIn=ServiceTask1,ServiceTask2

Response

[
  {
    "id": "aJobDefId",
    "processDefinitionId": "aProcDefId",
    "processDefinitionKey": "aProcDefKey",
    "activityId": "ServiceTask1",
    "jobType": "asynchronous-continuation",
    "jobConfiguration": "",
    "suspended": false
  },
  {
    "id": "aJobDefId",
    "processDefinitionId": "aProcDefId",
    "processDefinitionKey": "aProcDefKey",
    "activityId": "ServiceTask2",
    "jobType": "asynchronous-continuation",
    "jobConfiguration": "",
    "suspended": true
  }
]

Query for the number of job definitions that fulfill given parameters. Takes the same parameters as the get job definitions method.

Method

GET /job-definition/count

Parameters

Query Parameters

Result

A json object that contains the count as the only property.

Response codes

Example

Request

GET /job-definition/count?activityIdIn=ServiceTask1,ServiceTask2

Response

{"count": 2}

Query for job definitions that fulfill given parameters. This method is slightly more powerful than the GET query, because it allows to filter by multiple job definitions of types String, Number or Boolean.

Method

POST /job-definition

Parameters

Query Parameters

Request Body

A json object with the following properties:

Result

A json array of job definition objects. Each job definition object has the following properties:

Response codes

Example

Request

POST /job-definition

Request body:

{
  "activityIdIn": 
    [
      ServiceTask1, ServiceTask2
    ]
}

Response

[
  {
    "id": "aJobDefId",
    "processDefinitionId": "aProcDefId",
    "processDefinitionKey": "aProcDefKey",
    "activityId": "ServiceTask1",
    "jobType": "asynchronous-continuation",
    "jobConfiguration": "",
    "suspended": false
  },
  {
    "id": "aJobDefId",
    "processDefinitionId": "aProcDefId",
    "processDefinitionKey": "aProcDefKey",
    "activityId": "ServiceTask2",
    "jobType": "asynchronous-continuation",
    "jobConfiguration": "",
    "suspended": true
  }
]

Query for the number of job definitions that fulfill given parameters. This method takes the same message body as the POST query and is thus slightly more powerful than the GET query count.

Method

POST /job-definition/count

Parameters

Request Body

A json object with the following properties:

Result

A json object that contains the count as the only property.

Response codes

Example

Request

POST /job-definition/count

Request body:

{
  "activityIdIn": 
    [
      ServiceTask1, ServiceTask2
    ]
}

Response

{"count": 2}

Activate or suspend a given job definition by id.

Method

PUT /job-definition/{id}/suspended

Parameters

Path Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

PUT /job-definition/aJobDefinitionId/suspended

{
  "suspended" : true,
  "includeJobs" : true,
  "executionDate" : "2013-11-21T10:49:45"
}

Response

Status 204. No content.

Activate or suspend job definitions with the given process definition id.

Method

PUT /job-definition/suspended

Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

PUT /job-definition/suspended

{
  "processDefinitionId" : "aProcessDefinitionId",
  "suspended" : true,
  "includeJobs" : true,
  "executionDate" : "2013-11-21T10:49:45"
}

Response

Status 204. No content.

Activate or suspend job definitions with the given process definition key.

Method

PUT /job-definition/suspended

Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

PUT /job-definition/suspended

{
  "processDefinitionKey" : "aProcessDefinitionKey",
  "suspended" : true,
  "includeJobs" : true,
  "executionDate" : "2013-11-21T10:49:45"
}

Response

Status 204. No content.

Set the number of retries of all failed jobs associated with the given job definition id.

Method

PUT /job-definition/{id}/retries

Parameters

Path Parameters

Request Body

A json object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

PUT /job-definition/aJobDefId/retries

Request body:

{"retries": 3}

Response

Status 204. No content.

Retrieves a single job according to the Job interface in the engine.

Method

GET /job/{id}

Parameters

Path Parameters

Result

A json object corresponding to the Job interface in the engine. Its properties are as follows: