REST API

Introduction

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.

Configuring Authentication

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 neccessarily 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.

Usage with a pre-built distribution

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.

Embedding the API

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 camunda engine rest classes that you need
        classes.add(org.camunda.bpm.engine.rest.impl.ProcessEngineRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.ProcessDefinitionRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.ProcessInstanceRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.TaskRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.IdentityRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.MessageRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.JobRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.ExecutionRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.VariableInstanceRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.UserRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.GroupRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.AuthorizationRestServiceImpl.class);
        classes.add(org.camunda.bpm.engine.rest.impl.history.HistoryRestServiceImpl.class);
        // mandatory
        classes.add(org.camunda.bpm.engine.rest.mapper.JacksonConfigurator.class);
        classes.add(org.camunda.bpm.engine.rest.exception.RestExceptionHandler.class);
        classes.add(org.camunda.bpm.engine.rest.exception.ProcessEngineExceptionHandler.class);
        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.

Delete Authorization

Deletes an authorization by id.

Method

DELETE /authorization/{id}

Parameters

Path Parameters

Name Description
id The id of the authorization to be deleted.

Request Body

Empty.

Result

This method returns no content.

Response codes

Code Media type Description
200 application/json Request successful.
403 application/json If the authenticated user is unauthorized to delete the resource instance. See the Introduction for the error response format.
404 application/json Authorization cannot be found. See the Introduction for the error response format.

Example

Request

DELETE /authorization/anAuthorizationId

Response

Status 204. No content.

Get Single Authorization

Retrieves a single authorization by Id.

Method

GET /authorization/{id}

Parameters

Path Parameters

Name Description
id The id of the authorization to be retrieved.

Result

A json array with the following properties:

Name Value Description
id String The id of the authorization.
type Integer The type of the authorization. (0=global, 1=grant, 2=revoke).
permissions Array of Strings An array of strings representing the permissions assigned by this authentication.
userId String The id of the user this authorization has been created for. The value "\*" represents a global authorization ranging over all users.
groupId String The id of the group this authorization has been created for.
resourceType Integer An integer representing the resource type.
resourceId String The resource Id. The value "\*" represents an authorization ranging over all instances of a resource.
links Object A json array containing links to interact with the resource. The links contain only operations that the currently authenticated user would be authorized to perform.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Authorization with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /authorization/anAuthorizationId

Response

Status 200.

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

Perform an Authorization Check

Performs an authorization check for the currently authenticated user.

Method

GET /authorization/check

Parameters

Query Parameters

Name Description Required?
permissionName String value representing the permission name to check for. Yes
permissionValue String representation of an integer value representing the permission value to check for. Yes
resourceName String value for the name of the resource to check permissions for. Yes
resourceType String representation of an integer value identifying the resource type to check permissions for. Yes
resourceId The id of the resource to check permissions for. If left blank, a check for global permissions on the resource is performed. No

Result

A json array with the following properties:

Name Value Description
permissionName String Name of the permission which was checked.
resourceName String The name of the resource for which the permission check was performed.
resourceId String The id of the resource for which the permission check was performed.
isAuthorized Boolean True / false for isAuthorized.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Authorization with given id does not exist. See the Introduction for the error response format.

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}

Get Authorizations

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

Name Description
id Filter by the id of the authorization.
type Filter by the type of the authorization.
userIdIn Filter by a comma-seperated list of userIds
groupIdIn Filter by a comma-seperated list of groupIds
resourceType Filter by resource type
resourceId Filter by resource Id.
sortBy Sort the results lexicographically by a given criterion. Valid values are resourceType, and resourceId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the authorization.
type Integer The type of the authorization. (0=global, 1=grant, 2=revoke).
permissions String An array of Strings holding the permissions provided by this authorization.
userId String The id of the user this authorization has been created for. The value "\*" represents a global authorization ranging over all users.
groupId String The id of the group this authorization has been created for.
resourceType Integer An integer representing the resource type.
resourceId String The resource Id. The value "\*" represents an authorization ranging over all instances of a resource.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy is specified. See the Introduction for the error response format.

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": "*"}]

Get Authorizations Count

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

Method

GET /authorization/count

Parameters

Query Parameters

Name Description
id Filter by the id of the authorization.
type Filter by the type of the authorization.
userIdIn Filter by a comma-seperated list of userIds
groupIdIn Filter by a comma-seperated list of groupIds
resourceType Filter by resource type
resourceId Filter by resource Id.

Result

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

Name Value Description
count Number The number of matching authorizations.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy is specified. See the Introduction for the error response format.

Example

Request

GET /authorization/count?userIdIn=jonny1,jonny2

Response

Status 200.

{"count": 2}

Authorization Resource Options

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

Name Value Description
method String The HTTP method to use for the interaction.
href String The interaction URL
rel String The relation of the interaction (i.e., a symbolic name representing the nature of the interaction). Examples: create, delete ...

Response codes

Code Media type Description
200 application/json Request successful.

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"}]}

Create a new Authorization

Creates a new authorization

Method

POST /authorization/create

Parameters

Request Body

A json object with the following properties:

Name Value Description
type Integer The type of the authorization. (0=global, 1=grant, 2=revoke).
permissions String An array of Strings holding the permissions provided by this authorization.
userId String The id of the user this authorization has been created for. The value "\*" represents a global authorization ranging over all users.
groupId String The id of the group this authorization has been created for.
resourceType Integer An integer representing the resource type.
resourceId String The resource Id. The value "\*" represents an authorization ranging over all instances of a resource.

Result

A json array with the following properties:

Name Value Description
id String The id of the authorization.
type Integer The type of the authorization. (0=global, 1=grant, 2=revoke).
permissions String An array of Strings holding the permissions provided by this authorization.
userId String The id of the user this authorization has been created for. The value "\*" represents a global authorization ranging over all users.
groupId String The id of the group this authorization has been created for.
resourceType Integer An integer representing the resource type.
resourceId String The resource Id. The value "\*" represents an authorization ranging over all instances of a resource.
links Object A json array containing links to interact with the resource. The links contain only operations that the currently authenticated user would be authorized to perform.

Response codes

Code Media type Description
200 application/json Request successful.
403 application/json If the authenticated user is unauthorized to create an instance of this resource. See the Introduction for the error response format.
500 application/json The authorization could not be updated due to an internal server error. See the Introduction for the error response format.

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"}
  ]}

Update a Single Authorization

Updates a single authorization.

Method

PUT /authorization/{id}

Parameters

Path Parameters

Name Description
id The id of the authorization to be updated.

Request Body

A json object with the following properties:

Name Value Description
permissions Integer An integer holding the permissions provided by this authorization.
userId String The id of the user this authorization has been created for. The value "\*" represents a global authorization ranging over all users.
groupId String The id of the group this authorization has been created for.
resourceType Integer An integer representing the resource type.
resourceId String The resource Id. The value "\*" represents an authorization ranging over all instances of a resource.

Result

Empty.

Response codes

Code Media type Description
204 Empty. Request successful.
403 application/json If the authenticated user is unauthorized to update this resource. See the Introduction for the error response format.
404 application/json If the authorization with the requested Id cannot be found.
500 application/json The authorization could not be updated due to an internal server error. See the Introduction for the error response format.

Example

Request

PUT /authorization/anAuthorizationId

Request body:

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

Response

Empty.

Get Engine Names

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:

Name Value Description
name String The name of the process engine.

Response codes

Code Media type Description
200 application/json Request successful.

Example

Request

GET /engine

Response

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

Delete Local Execution Variable

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

Name Description
id The id of the execution to delete the variable from.
varId The name of the variable to delete.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.

Example

Request

DELETE /execution/anExecutionId/localVariables/aVarName

Response

Status 204. No content.

Get Single Execution

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

Method

GET /execution/{id}

Parameters

Path Parameters

Name Description
id The id of the execution to be retrieved.

Result

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

Name Value Description
id String The id of the execution.
processInstanceId String The id of the process instance that this execution instance belongs to.
ended Boolean A flag indicating whether the execution has ended.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Execution with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /execution/anExecutionId

Response

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

Get Local Execution Variable

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

Name Description
id The id of the execution to retrieve the variable for.
varId The name of the variable to get.

Result

A json object with the following properties:

Name Value Description
value String/Number/Boolean/Object Object serialization uses Jackson's POJO/bean property introspection feature.
type String The simple class name of the variable object.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Variable with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /execution/anExecutionId/localVariables/aVarName

Response

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

Get Local Execution Variables

Retrieves all variables of a given execution.

Method

GET /execution/{id}/localVariables

Parameters

Path Parameters

Name Description
id The id of the execution to retrieve the variables for.

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:

Name Value Description
value String/Number/Boolean/Object Object serialization uses Jackson's POJO/bean property introspection feature.
type String The simple class name of the variable object.

Response codes

Code Media type Description
200 application/json Request successful.
500 application/json Execution with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /execution/anExecutionId/localVariables

Response

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

Get Message Event Subscription

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

Method

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

Parameters

Path Parameters

Name Description
id The id of the execution that holds the subscription.
messageName The name of the message that the subscription corresponds to.

Result

A json object with the following properties:

Name Description
id The identifier of the event subscription.
eventType The type of the event. message for message events.
eventName The name of the event the subscription belongs to, as defined in the process model.
executionId The id of the execution the subscription belongs to.
processInstanceId The id of the process instance the subscription belongs to.
activityId The id of the activity that the event subscription belongs to. Corresponds to the id in the process model.
createdDate The time the subscription was created by the engine. Format yyyy-MM-dd'T'HH:mm:ss.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json A message subscription for the given name and execution does not exist. This may either mean that the execution does not exist, or that it is not subscribed on such a message. See the Introduction for the error response format.

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"}

Get Executions

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

Name Description
businessKey Filter by the business key of the process instances the executions belong to.
processDefinitionId Filter by the process definition the executions run on.
processDefinitionKey Filter by the key of the process definition the executions run on.
processInstanceId Filter by the id of the process instance the execution belongs to.
activityId Filter by the id of the activity the execution currently executes.
signalEventSubscriptionName Select only those executions that expect a signal of the given name.
messageEventSubscriptionName Select only those executions that expect a message of the given name.
active Only include active executions. Values may be true or false.
suspended Only include suspended executions. Values may be true or false.
variables Only include executions that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
processVariables Only include executions that belong to a process instance with variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are instanceId, definitionKey and definitionId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the execution.
processInstanceId String The id of the process instance that this execution instance belongs to.
ended Boolean A flag indicating whether the execution has ended.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /execution?variables=myVariable_eq_camunda

Response

Status 200.

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

Get Executions Count

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

Name Description
businessKey Filter by the business key of the process instances the executions belong to.
processDefinitionId Filter by the process definition the executions run on.
processDefinitionKey Filter by the key of the process definition the executions run on.
processInstanceId Filter by the id of the process instance the execution belongs to.
activityId Filter by the id of the activity the execution currently executes.
signalEventSubscriptionName Select only those executions that expect a signal of the given name.
messageEventSubscriptionName Select only those executions that expect a message of the given name.
active Only include active executions. Values may be true or false.
suspended Only include suspended executions. Values may be true or false.
variables Only include executions that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
processVariables Only include executions that belong to a process instance with variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals.
key and value may not contain underscore or comma characters.

Result

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

Name Value Description
count Number The number of matching executions.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /execution/count?variables=myVariable_eq_camunda

Response

{"count": 1}

Update/Delete Local Execution Variables

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

Name Description
id The id of the execution to set variables for.

Request Body

A json object with the following properties:

Name Description
modifications A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object. A variable value object has has the property value, which is the value to update, and type, which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date.
deletions An array of String keys of variables to be deleted.

Result

This method returns no content.

Response codes

Code Media type Description
204 application/json Request successful.
400 application/json The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.
500 application/json Update or delete could not be executed, for example because the execution does not exist.

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.

Trigger Message Event Subscription

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

Name Description
id The id of the execution to submit the message to.
messageName The name of the message that the addressed subscription corresponds to.

Request Body

A json object with the following properties:

Name Description
messageName The name of the message to deliver.
variables A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object. A variable value object has has the property value, which is the value to update, and type, which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.
500 application/json The addressed execution has no pending message subscriptions for the given message. See the Introduction for the error response format.

Example

Request

POST /execution/anExecutionId/messageSubscriptions/someMessage/trigger

Request body:

{"messageName" : "aMessage",
"variables" :
    {"aVariableName" : {"value" : true, "type": "Boolean"},
    "anotherVariableName" : {"value" : 42, "type": "Integer"}}
}

Response

Status 204. No content.

Get Executions (POST)

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

Name Description
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Request Body

A json object with the following properties:

Name Description
businessKey Filter by the business key of the process instances the executions belong to.
processDefinitionId Filter by the process definition the executions run on.
processDefinitionKey Filter by the key of the process definition the executions run on.
processInstanceId Filter by the id of the process instance the execution belongs to.
activityId Filter by the id of the activity the execution currently executes.
signalEventSubscriptionName Select only those executions that expect a signal of the given name.
messageEventSubscriptionName Select only those executions that expect a message of the given name.
active Only include active executions. Values may be true or false.
suspended Only include suspended executions. Values may be true or false.
variables A json array to only include executions that have variables with certain values.
The array consists of objects with the three properties key, operator and value. key (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.
valuemay be String, Numberor Boolean.
Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore characters.
processVariables A json array to only include executions that belong to a process instance with variables with certain values.
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals.
key and value may not contain underscore characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are instanceId, definitionKey and definitionId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
id String The id of the execution.
processInstanceId String The id of the process instance that this execution instance belongs to.
ended Boolean A flag indicating whether the execution has ended.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

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}]

Get Executions Count (POST)

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:

Name Description
businessKey Filter by the business key of the process instances the executions belong to.
processDefinitionId Filter by the process definition the executions run on.
processDefinitionKey Filter by the key of the process definition the executions run on.
processInstanceId Filter by the id of the process instance the execution belongs to.
activityId Filter by the id of the activity the execution currently executes.
signalEventSubscriptionName Select only those executions that expect a signal of the given name.
messageEventSubscriptionName Select only those executions that expect a message of the given name.
active Only include active executions. Values may betrue or false.
suspended Only include suspended executions. Values may be true or false.
variables A json array to only include executions that have variables with certain values.
The array consists of objects with the three properties key, operator and value. key (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.
value may be String, Number or Boolean.
Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore characters.
processVariables A json array to only include executions that belong to a process instance with variables with certain values.
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals.
key and value may not contain underscore characters.

Result

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

Name Value Description
count Number The number of matching executions.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

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}

Trigger Execution

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

Name Description
id The id of the execution to signal.

Request Body

A json object with the following properties:

Name Description
variables A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object. A variable value object has has the propertyvalue, which is the value to update, andtype, which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date.

Result

This method returns no content.

Response codes

Code Media type Description
204 application/json Request successful.
400 application/json The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.

Example

Request

POST /execution/{id}/signal

Request body:

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

Response

Status 204. No content.

Put Local Execution Variable

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

Name Description
id The id of the execution to set the variable for.
varId The name of the variable to set.

Request Body

A json object with the following properties:

Name Description
value The value of the variable to set.
type The type of the variable to set. Valid types are Integer, Short, Long, Double, String, Boolean and Date.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.

Example

Request

PUT /execution/anExecutionId/localVariables/aVarName

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

Response

Status 204. No content.

Delete Group

Deletes a group by id.

Method

DELETE /group/{id}

Parameters

Path Parameters

Name Description
id The id of the group to be deleted.

Request Body

Empty.

Result

This method returns no content.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Group cannot be found. See the Introduction for the error response format.

Example

Request

DELETE /group/sales

Response

Status 204. No content.

Get Single Group

Retrieves a single group.

Method

GET /group/{id}

Parameters

Path Parameters

Name Description
id The id of the group to be retrieved.

Result

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

Name Value Description
id String The id of the group.
name String The name of the group.
type String The type of the group.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Execution with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /group/sales

Response

Status 200.

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

Get Groups

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

Name Description
id Filter by the id of the group.
name Filter by the name of the group.
nameLike Filter by the name that the parameter is a substring of.
type Filter by the type of the group.
member Only retrieve groups where the given user id is a member of.
sortBy Sort the results lexicographically by a given criterion. Valid values are id, name and type. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the group.
name String The name of the group.
type String The type of the group.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy is specified. See the Introduction for the error response format.

Example

Request

GET /group?name=Sales

Response

Status 200.

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

Get Groups Count

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

Method

GET /group/count

Parameters

Query Parameters

Name Description
id Filter by the id of the group.
name Filter by the name of the group.
nameLike Filter by the name that the parameter is a substring of.
type Filter by the type of the group.
member Only retrieve groups where the given user id is a member of.

Result

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

Name Value Description
count Number The number of matching groups.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy is specified. See the Introduction for the error response format.

Example

Request

GET /group/count?name=Sales

Response

Status 200.

{"count": 1}

Delete a Group Member

Removes a memeber from a group.

Method

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

Parameters

Path Parameters

Name Description
id The id of the group
userId The id of user to remove from the group

Request Body

Empty.

Result

This method returns no content.

Response codes

Code Media type Description
200 application/json Request successful.
500 application/json In case an error occurs. See the Introduction for the error response format.

Example

Request

DELETE /group/sales/members/jonny1

Response

Status 204. No content.

Create Group Member

Add a member to a group.

Method

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

Parameters

Request Body

None.

Result

None.

Response codes

Code Media type Description
204 Empty Request successful.
500 application/json In case an internal error occurs. See the Introduction for the error response format.

Example

Request

PUT /group/sales/members/jonny1

Request body:

Empty.

Response

None.

Group Resource Options

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 interal 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

Name Value Description
method String The HTTP method to use for the interaction.
href String The interaction URL
rel String The relation of the interaction (i.e., a symbolic name representing the nature of the interaction). Examples: create, delete ...

Response codes

Code Media type Description
200 application/json Request successful.

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 group

Create a new group.

Method

POST /group/create

Parameters

Request Body

A json object with the following properties:

Name Type Description
id String The id of the group.
name String The name of the group.
type String The type of the group.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
500 application/json The group could not be created due to an internal server error. See the Introduction for the error response format.

Example

Request

POST /group/create

Request body:

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

Response

Status 204. No content.

Update group

Updates a given group.

Method

PUT /group/{id}

Parameters

Path Parameters

Name Type Description
id String The id of the group.

Request Body

A json object with the following properties:

Name Type Description
id String The id of the group.
name String The name of the group.
type String The type of the group.

Result

Empty.

Response codes

Code Media type Description
204 Empty. Request successful.
404 application/json If the group with the requested Id cannot be found.
500 application/json The group could not be updated due to an internal server error. See the Introduction for the error response format.

Example

Request

PUT /group/sales

Request body:

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

Response

Empty.

Get Activity Instances (Historic)

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

Name Description
activityInstanceId Filter by activity instance id.
processInstanceId Filter by process instance id.
processDefinitionId Filter by process definition id.
executionId Filter by the id of the execution that executed the activity instance.
activityId Filter by the activity id (according to BPMN 2.0 XML).
activityName Filter by the activity name (according to BPMN 2.0 XML).
activityType Filter by activity type.
taskAssignee Only include activity instances that are user tasks and assigned to a given user.
finished Only include finished activity instances. Values may be true or false.
unfinished Only include unfinished activity instances. Values may be true or false.
sortBy Sort the results by a given criterion. Valid values are activityInstanceID, instanceId, executionId, activityId, activityName, activityType, startTime, endTime, duration, definitionId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the activity instance.
parentActivityInstanceId String The id of the parent activity instance, for example a sub process instance.
activityId String The id of the activity that this object is an instance of.
activityName String The name of the activity that this object is an instance of.
activityType String The type of the activity that this object is an instance of.
processDefinitionId String The id of the process definition that this process instance belongs to.
processInstanceId String The id of the process instance that this activity instance belongs to.
executionId String The id of the execution that executed this activity instance.
taskId String The id of the task that is associated to this activity instance. Is only set, if the activity is a user task.
assignee String The assignee of the task that is associated to this activity instance. Is only set, if the activity is a user task.
calledProcessInstanceId String The id of the called process instance. Is only set, if the activity is a call activity.
startTime String The time the instance was started. Has the format yyyy-MM-dd'T'HH:mm:ss.
endTime String The time the instance ended. Has the format yyyy-MM-dd'T'HH:mm:ss.
durationInMillis Number The time the instance took to finish (in milliseconds).

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

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}]

Get Activity Instances Count

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

Name Description
activityInstanceId Filter by activity instance id.
processInstanceId Filter by process instance id.
processDefinitionId Filter by process definition id.
executionId Filter by the id of the execution that executed the activity instance.
activityId Filter by the activity id (according to BPMN 2.0 XML).
activityName Filter by the activity name (according to BPMN 2.0 XML).
activityType Filter by activity type.
taskAssignee Only include activity instances that are user tasks and assigned to a given user.
finished Only include finished activity instances. Values may be true or false.
unfinished Only include unfinished activity instances. Values may be true or false.

Result

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

Name Value Description
count Number The number of matching historic activity instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid. See the Introduction for the error response format.

Example

Request

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

Response

{"count": 1}

Get Process Instances

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

Name Description
processInstanceIds Filter by process instance ids. Must be a comma-separated list of process instance ids.
processInstanceBusinessKey Filter by process instance business key.
superProcessInstanceId Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
processDefinitionId Filter by the process definition the instances run on.
processDefinitionKey Filter by the key of the process definition the instances run on.
processDefinitionKeyNotIn Exclude instances that belong to a set of process definitions. Must be a comma-separated list of process definition keys.
finished Only include finished process instances. Values may be true or false.
unfinished Only include unfinished process instances. Values may be true or false.
startedBy Only include process instances that were started by the given user.
startedBefore Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
variables Only include process instances that have/had variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results by a given criterion. Valid values are instanceId, definitionId, businessKey, startTime, endTime, duration. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the process instance.
superProcessInstanceId String The id of the parent process instance if exists.
processDefinitionId String The id of the process definition that this process instance belongs to.
businessKey String The business key of the process instance.
startTime String The time the instance was started. Has the format yyyy-MM-dd'T'HH:mm:ss.
endTime String The time the instance ended. Has the format yyyy-MM-dd'T'HH:mm:ss.
durationInMillis Number The time the instance took to finish (in milliseconds).
startUserId String The id of the user who started the process instance.
startActivityId String The id of the initial activity that was executed (e.g. a start event).
deleteReason String The provided delete reason in case the process instance was cancelled during execution.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

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"}]

Get Process Instances Count

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

Name Description
processInstanceIds Filter by process instance ids. Must be a comma-separated list of process instance ids.
processInstanceBusinessKey Filter by process instance business key.
superProcessInstanceId Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
processDefinitionId Filter by the process definition the instances run on.
processDefinitionKey Filter by the key of the process definition the instances run on.
processDefinitionKeyNotIn Exclude instances that belong to a set of process definitions. Must be a comma-separated list of process definition keys.
finished Only include finished process instances. Values may be true or false.
unfinished Only include unfinished process instances. Values may be true or false.
startedBy Only include process instances that were started by the given user.
startedBefore Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
variables Only include process instances that have/had variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.

Result

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

Name Value Description
count Number The number of matching historic process instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid. See the Introduction for the error response format.

Example

Request

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

Response

{"count": 1}

Get Variable Instances

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

Name Description
variableName Filter by variable name.
variableNameLike Restrict to variables with a name like the parameter.
variableValue Filter by variable value. Is treated as a String object on server side.
processInstanceId Filter by the process instance the variable belongs to.
sortBy Sort the results by a given criterion. Valid values are instanceId, variableName. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
name String The name of the variable instance.
type String The type of the variable instance.
value String The value of the variable instance.
processInstanceId String The id the process instance belongs to.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

Example

Request

GET /history/variable-instance?variableName=my_variable

Response

[{"name": "my_variable",
"type": "String",
"value": "my_value",
"processInstanceId": "aVariableInstanceProcInstId"}]

Get Variable Instances Count

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

Name Description
variableName Filter by variable name.
variableNameLike Restrict to variables with a name like the parameter.
variableValue Filter by variable value. Is treated as a String object on server side.
processInstanceId Filter by the process instance the variable belongs to. See the Introduction for the error response format.

Result

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

Name Value Description
count Number The number of matching historic variable instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid.

Example

Request

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

Response

{"count": 1}

Get Process Instances (POST)

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

firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Request Body

A json object with the following properties:

Name Description
processInstanceIds Filter by process instance ids. Must be a comma-separated list of process instance ids.
processInstanceBusinessKey Filter by process instance business key.
superProcessInstanceId Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
processDefinitionId Filter by the process definition the instances run on.
processDefinitionKey Filter by the key of the process definition the instances run on.
processDefinitionKeyNotIn Exclude instances that belong to a set of process definitions. Must be a comma-separated list of process definition keys.
finished Only include finished process instances. Values may be true or false.
unfinished Only include unfinished process instances. Values may be true or false.
startedBy Only include process instances that were started by the given user.
startedBefore Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
variables A json array to only include process instances that have/had variables with certain values.
The array consists of objects with the three properties name, operator and value. name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.
value may be String, Number or Boolean.
Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
sortBy Sort the results by a given criterion. Valid values are instanceId, definitionId, businessKey, startTime, endTime, duration. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
id String The id of the process instance.
superProcessInstanceId String The id of the parent process instance if exists.
processDefinitionId String The id of the process definition that this process instance belongs to.
businessKey String The business key of the process instance.
startTime String The time the instance was started. Has the format yyyy-MM-dd'T'HH:mm:ss.
endTime String The time the instance ended. Has the format yyyy-MM-dd'T'HH:mm:ss.
durationInMillis Number The time the instance took to finish (in milliseconds).
startUserId String The id of the user who started the process instance.
startActivityId String The id of the initial activity that was executed (e.g., a start event).
deleteReason String The provided delete reason in case the process instance was cancelled during execution.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

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"}]

Get Process Instances Count (POST)

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:

Name Description
processInstanceIds Filter by process instance ids. Must be a comma-separated list of process instance ids.
processInstanceBusinessKey Filter by process instance business key.
superProcessInstanceId Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
processDefinitionId Filter by the process definition the instances run on.
processDefinitionKey Filter by the key of the process definition the instances run on.
processDefinitionKeyNotIn Exclude instances that belong to a set of process definitions. Must be a comma-separated list of process definition keys.
finished Only include finished process instances. Values may be true or false.
unfinished Only include unfinished process instances. Values may be true or false.
startedBy Only include process instances that were started by the given user.
startedBefore Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
variables A json array to only include process instances that have/had variables with certain values.
The array consists of objects with the three properties name, operator and value. name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.
value may be String, Number or Boolean.
Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.

Result

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

Name Value Description
count Number The number of matching historic process instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid. See the Introduction for the error response format.

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}

Get Variable Instances (POST)

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

firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Request body

A json object with the following properties:

Name Description
variableName Filter by variable name.
variableNameLike Restrict to variables with a name like the parameter.
variableValue Filter by variable value. May be String, Number or Boolean.
processInstanceId Filter by the process instance the variable belongs to.
sortBy Sort the results by a given criterion. Valid values are instanceId, variableName. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
name String The name of the variable instance.
type String The type of the variable instance.
value String The value of the variable instance.
processInstanceId String The id the process instance belongs to.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

Example

Request

POST /history/variable-instance

Request body:

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

Response

[{"name": "someVariable",
"type": "Integer",
"value": 42,
"processInstanceId": "aProcInstId"}]

Get Variable Instances Count (POST)

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:

Name Description
variableName Filter by variable name.
variableNameLike Restrict to variables with a name like the parameter.
variableValue Filter by variable value. May be String, Number or Boolean.
processInstanceId Filter by the process instance the variable belongs to.

Result

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

Name Value Description
count Number The number of matching historic variable instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid. See the Introduction for the error response format.

Example

Request

POST /history/variable-instance/count

Request body:

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

Response

{"count" : 1}

Get a User's Groups

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

Method

GET /identity/groups

Parameters

Query Parameters

Name Description
userId The id of the user to get the groups for.

Result

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

Name Value Description
groups Array A json array of group object. Every group object has an id property and a name property.
groupUsers Array A json array that contains all users that are member in one of the groups.
Every user object has four properties: id, firstName, lastName and displayName. The displayName is the id, if firstName and lastName are null and firstName lastName otherwise.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json If the userId query parameter is missing. See the Introduction for the error response format.

Example

Request

GET /identity/groups?userId=aUserId

Response

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

Get Single Job

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

Method

GET /job/{id}

Parameters

Path Parameters

Name Description
id The id of the job to be retrieved.

Result

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

Name Value Description
id String The id of the job.
dueDate String The date on which this job is supposed to be processed.
processInstanceId String The id of the process instance which execution created the job.
executionId String The specific execution id on which the job was created.
retries Number The number of retries this job has left.
exceptionMessage String The message of the exception that occurred, the last time the job was executed. Is null when no exception occurred.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Job with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /job/aJobId

Response

{
  "id": "aJobId",
  "dueDate": "2013-07-17'T'17:00:00",
  "processInstanceId": "aProcessInstanceId",
  "executionId": "anExecutionId",
  "retries": 0,
  "exceptionMessage": "An exception Message"
}

Get Exception Stacktrace

Retrieves the corresponding exception stacktrace to the passed job id.

Method

GET /job/{id}/stacktrace

Parameters

Path Parameters

Name Description
id The id of the job to get the exception stacktrace for.

Result

The result is the corresponding stacktrace as a plain text.

Response codes

Code Media type Description
200 text/plain Request successful.
404 application/json Job with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /job/aJobId/stacktrace

Response

java.lang.RuntimeException: A exception message!
  at org.camunda.bpm.pa.service.FailingDelegate.execute(FailingDelegate.java:10)
  at org.camunda.bpm.engine.impl.delegate.JavaDelegateInvocation.invoke(JavaDelegateInvocation.java:34)
  at org.camunda.bpm.engine.impl.delegate.DelegateInvocation.proceed(DelegateInvocation.java:37)
  ...

Get Jobs

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

Method

GET /job

Parameters

Query Parameters

Name Description
jobId Filter by job id.
processInstanceId Only select jobs which exist for the given process instance.
executionId Only select jobs which exist for the given execution.
withRetriesLeft Only select jobs which have retries left.
executable Only select jobs which are executable, i.e., retries > 0 and duedate is null or duedate is in the past.
timers Only select jobs that are timers. Cannot be used together with messages.
messages Only select jobs that are messages. Cannot be used together with timers.
dueDates Only select jobs where the duedate is lower or higher than the given date. Due date expressions are comma-separated and are structured as follows:
A valid condition value has the form operator_value. op is the comparison operator to be used and value the date value as string.

Valid operator values are: gt - greater than; lt - lower than.
value may not contain underscore or comma characters.
withException Only select jobs that failed due to an exception. Valid value is a boolean.
exceptionMessage Only select jobs that failed due to an exception with the given message.
noRetriesLeft Only select jobs which have no retries left.
sortBy Sort the results lexicographically by a given criterion. Valid values are jobId, executionId, processInstanceId, jobRetries and jobDueDate. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the job.
dueDate String The date on which this job is supposed to be processed.
processInstanceId String The id of the process instance which execution created the job.
executionId String The specific execution id on which the job was created.
retries Number The number of retries this job has left.
exceptionMessage String The message of the exception that occurred, the last time the job was executed. Is null when no exception occurred.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for due date comparison is used. See the Introduction for the error response format.

Example

Request

GET /job?dueDates=gt_2012-07-17'T'17:00:00,lt_2012-07-17'T'18:00:00

Response

[
  {
    "id": "aJobId",
    "dueDate": "2013-07-17'T'17:05:00",
    "processInstanceId": "aProcessInstanceId",
    "executionId": "anExecutionId",
    "retries": 0,
    "exceptionMessage": "An exception Message"
  },
  {
    "id": "anotherJobId",
    "dueDate": "2013-07-17'T'17:55:00",
    "processInstanceId": "aProcessInstanceId",
    "executionId": "anotherExecutionId",
    "retries": 0,
    "exceptionMessage": "Another exception Message"
  }
]

Get Jobs Count

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

Method

GET /job/count

Parameters

Query Parameters

Name Description
jobId Filter by job id.
processInstanceId Only select jobs which exist for the given process instance.
executionId Only select jobs which exist for the given execution.
withRetriesLeft Only select jobs which have retries left.
executable Only select jobs which are executable, i.e., retries > 0 and duedate is null or duedate is in the past.
timers Only select jobs that are timers. Cannot be used together with messages.
messages Only select jobs that are messages. Cannot be used together with timers.
dueDates Only select jobs where the duedate is lower or higher than the given date. Due date expressions are comma-separated and are structured as follows:
A valid condition value has the form operator_value. op is the comparison operator to be used and value the date value as string.

Valid operator values are: gt - greater than; lt - lower than.
value may not contain underscore or comma characters.
withException Only select jobs that failed due to an exception. Valid value is a boolean.
exceptionMessage Only select jobs that failed due to an exception with the given message.
noRetriesLeft Only select jobs which have no retries left.
sortBy Sort the results lexicographically by a given criterion. Valid values are jobId, executionId, processInstanceId, jobRetries and jobDueDate. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
count Number The number of matching executions.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for due date comparison is used. See the Introduction for the error response format.

Example

Request

GET /job?dueDates=gt_2012-07-17'T'17:00:00,lt_2012-07-17'T'18:00:00

Response

{"count": 2}

Execute Job

Executes the job. Note: The execution of the job happens in synchronously in the same thread.

Method

POST /job/{id}/execute

Parameters

Path Parameters

Name Description
id The id of the job to be executed.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
404 application/json Job with given id does not exist. See the Introduction for the error response format.
500 application/json The job could not be executed successfully. See the Introduction for the error response format.

Example

Request

PUT /job/aJobId/execute

Response

Status 204. No content.

Get Jobs (POST)

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

Method

POST /job

Parameters

Query Parameters

Name Description
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Request Body

A json object with the following properties:

Name Description
jobId Filter by job id.
processInstanceId Only select jobs which exist for the given process instance.
executionId Only select jobs which exist for the given execution.
withRetriesLeft Only select jobs which have retries left. Valid value is a boolean.
executable Only select jobs which are executable, ie. retries > 0 and duedate is null or duedate is in the past. Valid value is a boolean.
timers Only select jobs that are timers. Cannot be used together with messages. Valid value is a boolean.
messages Only select jobs that are messages. Cannot be used together with timers. Valid value is a boolean.
dueDates Only select jobs where the duedate is lower or higher than the given date. Due date expressions are comma-separated and are structured as follows:
A valid condition value has the form operator_value. op is the comparison operator to be used and value the date value as string.

Valid operator values are: gt - greater than; lt - lower than.
value may not contain underscore or comma characters.
withException Only select jobs that failed due to an exception. Valid value is a boolean.
exceptionMessage Only select jobs that failed due to an exception with the given message.
sortBy Sort the results lexicographically by a given criterion. Valid values are jobId, executionId, processInstanceId, jobRetries and jobDueDate. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
id String The id of the job.
dueDate String The date on which this job is supposed to be processed.
processInstanceId String The id of the process instance which execution created the job.
executionId String The specific execution id on which the job was created.
retries Number The number of retries this job has left.
exceptionMessage String The message of the exception that occurred, the last time the job was executed. Is null when no exception occurred.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for due date comparison is used. See the Introduction for the error response format.

Example

Request

POST /job

Request body:

{
  "dueDates": 
    [
      {
        "operator": "gt",
        "value": "2012-07-17'T'17:00:00"
      },
      {   
        "operator": "lt",
        "value": "2012-07-17'T'18:00:00"
      }
    ]
}

Response

[
  {
    "id": "aJobId",
    "dueDate": "2013-07-17'T'17:05:00",
    "processInstanceId": "aProcessInstanceId",
    "executionId": "anExecutionId",
    "retries": 0,
    "exceptionMessage": "An exception Message"
  },
  {
    "id": "anotherJobId",
    "dueDate": "2013-07-17'T'17:55:00",
    "processInstanceId": "aProcessInstanceId",
    "executionId": "anotherExecutionId",
    "retries": 0,
    "exceptionMessage": "Another exception Message"
  }
]

Get Jobs Count (POST)

Query for jobs 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/count

Parameters

Request Body

A json object with the following properties:

Name Description
jobId Filter by job id.
processInstanceId Only select jobs which exist for the given process instance.
executionId Only select jobs which exist for the given execution.
withRetriesLeft Only select jobs which have retries left. Valid value is a boolean.
executable Only select jobs which are executable, ie. retries > 0 and duedate is null or duedate is in the past. Valid value is a boolean.
timers Only select jobs that are timers. Cannot be used together with messages. Valid value is a boolean.
messages Only select jobs that are messages. Cannot be used together with timers. Valid value is a boolean.
dueDates Only select jobs where the duedate is lower or higher than the given date. Due date expressions are comma-separated and are structured as follows:
A valid condition value has the form operator_value. op is the comparison operator to be used and value the date value as string.

Valid operator values are: gt - greater than; lt - lower than.
value may not contain underscore or comma characters.
withException Only select jobs that failed due to an exception. Valid value is a boolean.
exceptionMessage Only select jobs that failed due to an exception with the given message.
sortBy Sort the results lexicographically by a given criterion. Valid values are jobId, executionId, processInstanceId, jobRetries and jobDueDate. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
count Number The number of matching executions.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for due date comparison is used. See the Introduction for the error response format.

Example

Request

POST /job

Request body:

{
  "dueDates": 
    [
      {
        "operator": "gt",
        "value": "2012-07-17'T'17:00:00"
      },
      {   
        "operator": "lt",
        "value": "2012-07-17'T'18:00:00"
      }
    ]
}

Response

{"count": 2}

Set Job Due Date

Updates the due date of a job.

Method

PUT /job/{id}/duedate

Parameters

Path Parameters

Name Description
id The id of the job to be updated.

Request Body

A json object with the following properties:

Name Description
duedate The date to set when the job has the next execution.

Result

This method returns no content.

Response codes


Code Media type Description
204 Request successful.
404 application/json Job with given id does not exist. See the Introduction for the error response format.
500 application/json The duedate could not be set successfully. See the Introduction for the error response format.

Example

Request

PUT /job/aJobId/duedate

Request body:

{"duedate": "2013-08-13 18:43:28"}

Response

Status 204. No content.

Set Job Retries

Sets the retries of the job to the given number of retries.

Method

PUT /job/{id}/retries

Parameters

Path Parameters

Name Description
id The id of the job to be updated.

Request Body

A json object with the following properties:

Name Description
retries The number of retries to set that a job has left.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
404 application/json Job with given id does not exist. See the Introduction for the error response format.
500 application/json The retries could not be set successfully. See the Introduction for the error response format.

Example

Request

PUT /job/aJobId/retries

Request body:

{"retries": 3}

Response

Status 204. No content.

Deliver a Message

Deliver a message to the process engine to either trigger a message start or intermediate message catching event. Internally, this maps to the engine's RuntimeService#correlateMessage methods. See more on the correlation behavior in the message event documentation.

Method

POST /message

Parameters

Request Body

A json object with the following properties:

Name Description
messageName The name of the message to deliver.
businessKey Used for correlation of process instances that wait for incoming messages. Will only correlate to executions that belong to a process instance with the provided business key.
correlationKeys Used for correlation of process instances that wait for incoming messages. Has to be a json object containg key-value pairs that are matched against process instance variables during correlation.
Each key is a variable name and each value a json variable value object. A variable value object has the property value, which is the value to update, and type, which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. Note: Process instance variables are the global variables of a process instance. Local variables of child executions (such as in subprocesses) are not considered!
processVariables A map of variables that is injected into the triggered execution or process instance after the message has been delivered. Each key is a variable name and each value a json variable value object. A variable value object has the property value, which is the value to update, and type, which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json No messageName was supplied or the message has not been correlated to exactly one entity (execution or process definition). Or the variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.

Example

Request

POST /message

Request body:

{"messageName" : "aMessage",
"businessKey" : "aBusinessKey",
"correlationKeys" : {
    "aVariable" : {"value" : "aValue", "type": "String"}
},
"processVariables" : {
    "aVariable" : {"value" : "aNewValue", "type": "String"},
    "anotherVariable" : {"value" : true, "type": "Boolean"}
}}

Response

Status 204. No content.

Get Single Definition

Retrieves a single process definition according to the ProcessDefinition interface in the engine.

Method

GET /process-definition/{id}

Parameters

Path Parameters

Name Description
id The id of the process definition to be retrieved.

Result

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

Name Value Description
id String The id of the process definition.
key String The key of the process definition, i.e., the id of the BPMN 2.0 XML process definition.
category String The category of the process definition.
description String The description of the process definition.
name String The name of the process definition.
version Number The version of the process definition that the engine assigned to it.
resource String The file name of the process definition.
deploymentId String The id of the process definition.
diagram String The file name of the process definition diagram, if exists.
suspended Boolean A flag indicating whether the definition is suspended.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Process definition with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /process-definition/aProcessDefinitionId

Response

{"id":"aProcessDefinitionId",
"key":"aKey",
"category":"aCategory",
"description":"aDescription",
"name":"aName",
"version":42,
"resource":"aResourceName",
"deploymentId":"aDeploymentId",
"diagram":"aResourceName",
"suspended":true}

Get Activity Instance Statistics

Retrieves runtime statistics of a given process definition grouped by activities. These statistics include the number of running activity instances, optionally the number of failed jobs and also optionally the number of incidents either grouped by incident types or for a specific incident type.
Note: This does not include historic data.

Method

GET /process-definition/{id}/statistics

Parameters

Path Parameters

Name Description
id The id of the process definition.

Query Parameters

Name Description
failedJobs Whether to include the number of failed jobs in the result or not. Valid values are true or false.
incidents Valid values for this property are true or false. If this property has been set to true the result will include for each occurred incident type the corresponding number of incidents. In the case of false the incidents will not be included in the result.
incidentsForType If this property has been set with any incident type (i.e., a String value) the result will only include the number of incidents for the assigned incident type.

Note: The query parameters incidents and incidentsForType are exclusive. It is not possible to send a request with both query parameters. In that case the response will be a bad request.

Result

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

Name Value Description
id String The id of the activity the results are aggregated for.
instances Number The total number of running instances of this activity.
failedJobs Number The total number of failed jobs for the running instances.
Note: Will be 0 (not null), if failed jobs were excluded.
incidents Array Each item in the resulting array is an object which contains the following properties:
  • incidentType: The type of the incident the number of incidents is aggregated for.
  • incidentCount: The total number of incidents for the corresponding incident type.
Note: Will be an empty array, if incidents or incidentsForType were excluded. Furthermore, the array will be also empty, if no incidents were found.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json If both query parameters incidents and incidentsForType were set. See the Introduction for the error response format.

Examples

Request with query parameter failedJobs=true

GET /process-definition/aProcessDefinitionId/statistics?failedJobs=true

Response

[{"id":"anActivity",
 "instances":123,
 "failedJobs":42,
 "incidents": []
 },
 {"id":"anotherActivity",
 "instances":124,
 "failedJobs":43,
 "incidents": []}]

Request with query parameter incidents=true

GET /process-definition/aProcessDefinitionId/statistics?incidents=true

Response

[{"id":"anActivity",
 "instances":123,
 "failedJobs":0,
 "incidents":
  [
    {"incidentType":"failedJob", "incidentCount": 42 },
    {"incidentType":"aIncident", "incidentCount": 20 }        
  ]
 },
 {"id":"anotherActivity",
 "instances":124,
 "failedJobs":0,
 "incidents":
  [
    { "incidentType":"failedJob", "incidentCount": 43 },
    { "incidentType":"aIncident", "incidentCount": 22 }
    { "incidentType":"anotherIncident", "incidentCount": 15 }
  ]
}]

Request with query parameter incidentsForType=aIncident

GET /process-definition/aProcessDefinitionId/statistics?incidentsForType=aIncident

Response

[{"id":"anActivity",
 "instances":123,
 "failedJobs":0,
 "incidents":
  [
    {"incidentType":"aIncident", "incidentCount": 20 }        
  ]        
 },
 {"id":"anotherActivity",
 "instances":124,
 "failedJobs":0,
 "incidents": []    
}]

Get Definitions

Query for process definitions that fulfill given parameters. Parameters may be the properties of process definitions, such as the name, key or version. The size of the result set can be retrieved by using the GET query count.

Method

GET /process-definition

Parameters

Query Parameters

Name Description
name Filter by process definition name.
nameLike Filter by process definition names that the parameter is a substring of.
deploymentId Filter by the deployment the id belongs to.
key Filter by process definition key, i.e., the id in the BPMN 2.0 XML. Exact match.
keyLike Filter by process definition keys that the parameter is a substring of.
category Filter by process definition category. Exact match.
categoryLike Filter by process definition categories that the parameter is a substring of.
ver Filter by process definition version.
latest Only include those process definitions that are latest versions. Values may be true or false.
resourceName Filter by the name of the process definition resource. Exact match.
resourceNameLike Filter by names of those process definition resources that the parameter is a substring of.
startableBy Filter by a user name who is allowed to start the process.
active Only include active process definitions. Values may be true or false.
suspended Only include suspended process definitions. Values may be true or false.
sortBy Sort the results lexicographically by a given criterion. Valid values are category, key, id, name, version and deploymentId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the process definition.
key String The key of the process definition, i.e., the id of the BPMN 2.0 XML process definition.
category String The category of the process definition.
description String The description of the process definition.
name String The name of the process definition.
version Number The version of the process definition that the engine assigned to it.
resource String The file name of the process definition.
deploymentId String The id of the process definition.
diagram String The file name of the process definition diagram, if exists.
suspended Boolean A flag indicating whether the definition is suspended.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

Example

Request

GET /process-definition?keyLike=Key&sortBy=category&sortOrder=asc

Response

[{"id":"aProcessDefinitionId",
"key":"aKey",
"category":"aCategory",
"description":"aDescription",
"name":"aName",
"version":42,
"resource":"aResourceName",
"deploymentId":"aDeploymentId",
"diagram":"aResourceName",
"suspended":true}]

Get Definitions Count

Request the number of process definitions that fulfill the query criteria. Takes the same filtering parameters as the GET query.

Method

GET /process-definition/count

Parameters

Query Parameters

Name Description
name Filter by process definition name.
nameLike Filter by process definition names that the parameter is a substring of.
deploymentId Filter by the deployment the id belongs to.
key Filter by process definition key, i.e., the id in the BPMN 2.0 XML. Exact match.
keyLike Filter by process definition keys that the parameter is a substring of.
category Filter by process definition category. Exact match.
categoryLike Filter by process definition categories that the parameter is a substring of.
ver Filter by process definition version.
latest Only include those process definitions that are latest versions. Values may be true or false.
resourceName Filter by the name of the process definition resource. Exact match.
resourceNameLike Filter by names of those process definition resources that the parameter is a substring of.
startableBy Filter by a user name who is allowed to start the process.
active Only include active process definitions. Values may be true or false.
suspended Only include suspended process definitions. Values may be true or false.

Result

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

Name Value Description
count Number The number of matching process definitions.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned of some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

Example

Request

GET /process-definition/count?keyLike=Key&version=47

Response

{"count": 1}

Get Start Form Key

Retrieves the key of the start form for a process definition. The form key corresponds to the FormData#formKey property in the engine.

Method

GET /process-definition/{id}/startForm

Parameters

Path Parameters

Name Description
id The id of the process definition to get the start form for.

Result

A json object containing the form key.

Name Value Description
key String The for key for the task.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Process definition with given id does not exist or has no start form defined. See the Introduction for the error response format.

Example

Request

GET /process-definition/anId/startForm

Response

{"key":"aFormKey"}

Get Process Instance Statistics

Retrieves runtime statistics of the process engine grouped by process definitions. These statistics include the number of running process instances, optionally the number of failed jobs and also optionally the number of incidents either grouped by incident types or for a specific incident type.
Note: This does not include historic data.

Method

GET /process-definition/statistics

Parameters

Query Parameters

Name Description
failedJobs Whether to include the number of failed jobs in the result or not. Valid values are true or false.
incidents Valid values for this property are true or false. If this property has been set to true the result will include for each occurred incident type the corresponding number of incidents. In the case of false the incidents will not be included in the result.
incidentsForType If this property has been set with any incident type (i.e., a string value) the result will only include the number of incidents for the assigned incident type.

Note: The query parameters incidents and incidentsForType are exclusive. It is not possible to send a request with both query parameters. In that case the response will be a bad request.

Result

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

Name Value Description
id String The id of the process definition the results are aggregated for.
instances Number The total number of running process instances of this process definition.
failedJobs Number The total number of failed jobs for the running instances.
Note: Will be 0 (not null), if failed jobs were excluded.
definition Object The process definition with the properties as described in the [get single definition](ref:#process-definition-get-single-definition) method.
incidents Array Each item in the resulting array is an object which contains the following properties:
  • incidentType: The type of the incident the number of incidents is aggregated for.
  • incidentCount: The total number of incidents for the corresponding incident type.
Note: Will be an empty array, if incidents or incidentsForType were excluded. Furthermore, the array will be also empty, if no incidents were found.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json If both query parameters incidents and incidentsForType were set. See the Introduction for the error response format.

Examples

Request with query parameter failedJobs=true

GET /process-definition/statistics?failedJobs=true

Response

[{"id":"aProcessDefinitionId",
  "instances":123,
  "failedJobs":42,
  "definition":
    {"id":"aProcessDefinitionId",
    "key":"aKey",
    "category":null,
    "description":null,
    "name":"aName",
    "version":0,
    "resource":null,
    "deploymentId":null,
    "diagram":null,
    "suspended":false},
  "incidents:" []
 },
 {"id":"aProcessDefinitionId:2",
  "instances":124,
  "failedJobs":43,
  "definition":
    {"id":"aProcessDefinitionId:2",
    "key":"aKey",
    "category":null,
    "description":null,
    "name":"aName",
    "version":0,
    "resource":null,
    "deploymentId":null,
    "diagram":null,
    "suspended":false},
  "incidents:" []        
}]

Request with query parameter incidents=true

GET /process-definition/statistics?incidents=true

Response

[{"id":"aProcessDefinitionId",
  "instances":123,
  "failedJobs":0,
  "definition":
    {"id":"aProcessDefinitionId",
    "key":"aKey",
    "category":null,
    "description":null,
    "name":"aName",
    "version":0,
    "resource":null,
    "deploymentId":null,
    "diagram":null,
    "suspended":false},
  "incidents":
  [
    {"incidentType":"failedJob", "incidentCount": 42 },
    {"incidentType":"aIncident", "incidentCount": 20 }        
  ]        
 },
 {"id":"aProcessDefinitionId:2",
  "instances":124,
  "failedJobs":0,
  "definition":
    {"id":"aProcessDefinitionId:2",
    "key":"aKey",
    "category":null,
    "description":null,
    "name":"aName",
    "version":0,
    "resource":null,
    "deploymentId":null,
    "diagram":null,
    "suspended":false},
  "incidents":
  [
    { "incidentType":"failedJob", "incidentCount": 43 },
    { "incidentType":"aIncident", "incidentCount": 22 }
    { "incidentType":"anotherIncident", "incidentCount": 15 }
  ]        
}]

Request with query parameter incidentsForType=aIncident

GET /process-definition/statistics?incidentsForType=aIncident

Response

[{"id":"aProcessDefinitionId",
  "instances":123,
  "failedJobs":0,
  "definition":
    {"id":"aProcessDefinitionId",
    "key":"aKey",
    "category":null,
    "description":null,
    "name":"aName",
    "version":0,
    "resource":null,
    "deploymentId":null,
    "diagram":null,
    "suspended":false},
  "incidents":
  [
    {"incidentType":"aIncident", "incidentCount": 20 }        
  ]        
 },
 {"id":"aProcessDefinitionId:2",
  "instances":124,
  "failedJobs":0,
  "definition":
    {"id":"aProcessDefinitionId:2",
    "key":"aKey",
    "category":null,
    "description":null,
    "name":"aName",
    "version":0,
    "resource":null,
    "deploymentId":null,
    "diagram":null,
    "suspended":false},
  "incidents": []        
}]

Get BPMN 2.0 XML

Retrieves the BPMN 2.0 XML of this process definition.

Method

GET /process-definition/{id}/xml

Parameters

Path Parameters

Name Description
id The id of the process definition.

Result

A json object containing the id of the definition and the BPMN 2.0 XML.

Name Value Description
id String The id of the process definition.
bpmn20Xml String An escaped XML string containing the XML that this definition was deployed with. Carriage returns, line feeds and quotation marks are escaped.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Process definition with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /process-definition/aProcessDefinitionId/xml

Response

{"id":"aProcessDefinitionId",
"bpmn20Xml":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\r\n<definitions xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
...
<userTask id=\"approveInvoice\" camunda:expression=\"${true}\" name=\"approve invoice\">\r\n
..."}

Start Process Instance

Instantiates a given process definition. Process variables may be supplied in the request body.

Method

POST /process-definition/{id}/start

Parameters

Path Parameters

Name Description
id The id of the process definition to be retrieved.

Request Body

A json object with the following properties:

Name Description
variables A json object containing the variables the process is to be initialized with. Variable names are property keys of this object and variable values are json objects with a value and a type property (see example below). Valid variable values are Boolean, Number, String and Date values.

Result

A json object representing the newly created process instance. Properties are:

Name Value Description
id String The id of the process instance.
definitionId String The id of the process definition.
businessKey String The business key of the process instance.
ended Boolean A flag indicating whether the instance is still running.
suspended Boolean A flag indicating whether the instance is suspended.
links Object A json array containing links to interact with the instance.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json The instance could not be created due to an invalid variable value. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.
500 application/json The instance could not be created successfully. See the Introduction for the error response format.

Example

Request

POST /process-definition/aProcessDefinitionId/start

Request body:

{"variables": 
    {"aVariable" : {"value" : "aStringValue", "type": "String"},
     "anotherVariable" : {"value" : true, "type": "Boolean"}}}

Response

{"links":[{"method": "GET", "href":"http://localhost:8080/rest-test/process-instance/anId","rel":"self"}],
"id":"anId",
"definitionId":"aProcessDefinitionId",
"businessKey":null,
"ended":false,
"suspended":false}

Delete Process Instance

Deletes a running process instance.

Method

DELETE /process-instance/{id}

Parameters

Path Parameters

Name Description
id The id of the process instance to be retrieved.

Result

This method returns no content.

Response codes

Code Media type Description
204 application/json Request successful.
404 application/json Process instance with given id does not exist. See the Introduction for the error response format.

Example

Request

DELETE /process-instance/aProcessInstanceId

Response

Status 204. No content.

Delete Single Process Variable

Deletes a variable of a given process instance.

Method

DELETE /process-instance/{id}/variables/{varId}

Parameters

Path Parameters

Name Description
id The id of the process instance to delete the variable from.
varId The name of the variable to delete.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.

Example

Request

DELETE /process-instance/aProcessInstanceId/variables/aVarName

Response

Status 204. No content.

Get Single Instance

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

Method

GET /process-instance/{id}

Parameters

Path Parameters

Name Description
id The id of the process instance to be retrieved.

Result

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

Name Value Description
id String The id of the process instance.
definitionId String The id of the process definition this instance belongs to.
businessKey String The business key of the process instance.
ended Boolean A flag indicating whether the process instance has ended.
suspended Boolean A flag indicating whether the process instance is suspended.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Process instance with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /process-instance/aProcessInstanceId

Response

{"id":"aProcessInstanceId",
"definitionId":"aProcDefId",
"businessKey":"aKey",
"ended":false,
"suspended":false}

Get Activity Instance

Retrieves an Activity Instance (Tree) for a given process instance.

Method

GET /process-instance/{id}/activity-instances

Parameters

Path Parameters

Name Description
id The id of the process instance for which the activity instance should be retrieved.

Result

A json object corresponding to the Activity Instance tree of the given process instance.

The properties of an activity instance are as follows:

Name Value Description
id String The id of the activity instance.
activityId String The id of activity.
processInstanceId String The id of the process instance this activity instance is part of.
processDefinitionId String The id of the process definition.
childActivityInstances List of activityInstance A list of child activity instances.
childTransitionInstances List of transitionInstance A list of child transition instances. A transition instance represents an execution waiting in an asynchronous continuation.
executionIds List of String A list of execution ids.

The properties of a transition instance are as follows:

Name Value Description
id String The id of the transition instance.
activityId String The id of activity that is about to be entered
processInstanceId String The id of the process instance.
processDefinitionId String The id of the process definition.
executionId List of String A list of execution ids.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Process instance with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /process-instance/aProcessInstanceId/activity-instances

Response

{
  "id": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
  "parentActivityInstanceId": null,
  "activityId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
  "processInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
  "processDefinitionId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
  "childActivityInstances": [
      {
          "id": "SubProcess_1:8f72bca4-d505-11e2-bafa-3c970e140ef1",
          "parentActivityInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
          "activityId": "SubProcess_1",
          "processInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
          "processDefinitionId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
          "childActivityInstances": [],
          "childTransitionInstances": [
              {
                  "id": "8f72bca9-d505-11e2-bafa-3c970e140ef1",
                  "parentActivityInstanceId": "SubProcess_1:8f72bca4-d505-11e2-bafa-3c970e140ef1",
                  "processInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
                  "processDefinitionId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
                  "targetActivityId": "ServiceTask_1",
                  "executionId": "8f72bca9-d505-11e2-bafa-3c970e140ef1"
              },
              {
                  "id": "8f72bcaa-d505-11e2-bafa-3c970e140ef1",
                  "parentActivityInstanceId": "SubProcess_1:8f72bca4-d505-11e2-bafa-3c970e140ef1",
                  "processInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
                  "processDefinitionId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
                  "targetActivityId": "ServiceTask_2",
                  "executionId": "8f72bcaa-d505-11e2-bafa-3c970e140ef1"
              }
          ],
          "executionIds": [
              "8f72bc9f-d505-11e2-bafa-3c970e140ef1"
          ]
      }
  ],
  "childTransitionInstances": [],
  "executionIds": [
      "8f72bc9f-d505-11e2-bafa-3c970e140ef1"
  ]
}

Get Instances

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

Method

GET /process-instance

Parameters

Query Parameters

Name Description
processInstanceIds Filter by a comma-separated list of process instance ids.
businessKey Filter by process instance business key.
processDefinitionId Filter by the process definition the instances run on.
processDefinitionKey Filter by the key of the process definition the instances run on.
superProcessInstance Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstance Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id.
active Only include active process instances. Values may be true or false.
suspended Only include suspended process instances. Values may be true or false.
variables Only include process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are instanceId, definitionKey and definitionId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the process instance.
definitionId String The id of the process definition that this process instance belongs to.
businessKey String The business key of the process instance.
ended Boolean A flag indicating whether the process instance has ended.
suspended Boolean A flag indicating whether the process instance is suspended.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /process-instance?variables=myVariable_eq_camunda,mySecondVariable_neq_aBadValue

Response

[{"links":[],
 "id":"anId",
 "definitionId":"aProcDefId",
 "businessKey":"aKey",
 "ended":false,
 "suspended":false}]

Get Instances Count

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

Method

GET /process-instance/count

Parameters

Query Parameters

Name Description
processInstanceIds Filter by a comma-separated list of process instance ids.
businessKey Filter by process instance business key.
processDefinitionId Filter by the process definition the instances run on.
processDefinitionKey Filter by the key of the process definition the instances run on.
superProcessInstance Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstance Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id.
active Only include active process instances. Values may be true or false.
suspended Only include suspended process instances. Values may be true or false.
variables Only include process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.

Result

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

Name Value Description
count Number The number of matching process instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /process-instance/count?variables=myVariable_eq_camunda

Response

{"count": 1}

Get Single Process Variable

Retrieves a variable of a given process instance.

Method

GET /process-instance/{id}/variables/{varId}

Parameters

Path Parameters

Name Description
id The id of the process instance to retrieve the variable for.
varId The name of the variable to get.

Result

A json object with the following properties:

Name Value Description
value String/Number/Boolean/Object Object serialization uses Jackson's POJO/bean property introspection feature.
type String The simple class name of the variable object.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Variable with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /process-instance/aProcessInstanceId/variables/aVarName

Response

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

Get Process Variables

Retrieves all variables of a given process instance.

Method

GET /process-instance/{id}/variables

Parameters

Path Parameters

Name Description
id The id of the process instance to retrieve the variables for.

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:

Name Value Description
value String/Number/Boolean/Object Object serialization uses Jackson's POJO/bean property introspection feature.
type String The simple class name of the variable object.

Response codes

Code Media type Description
200 application/json Request successful.
500 application/json Process instance with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /process-instance/aProcessInstanceId/variables

Response

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

Get Instances (POST)

Query for process instances 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 process variables of types String, Number or Boolean.

Method

POST /process-instance

Parameters

Query Parameters

Name Description
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Request Body

A json object with the following properties:

Name Description
processInstanceIds Filter by a list of process instance ids. Must be a json array of Strings.
businessKey Filter by process instance business key.
processDefinitionId Filter by the process definition the instances run on.
processDefinitionKey Filter by the key of the process definition the instances run on.
superProcessInstance Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstance Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id.
active Only include active process instances. Values may be true or false.
suspended Only include suspended process instances. Values may be true or false.
variables A json array to only include process instances that have variables with certain values.
The array consists of objects with the three properties name, operator and value. name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.
value may be String, Number or Boolean.
Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
sortBy Sort the results lexicographically by a given criterion. Valid values are instanceId, definitionKey and definitionId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
id String The id of the process instance.
definitionId String The id of the process definition that this process instance belongs to.
businessKey String The business key of the process instance.
ended Boolean A flag indicating whether the process instance has ended.
suspended Boolean A flag indicating whether the process instance is suspended.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /process-instance

Request body:

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

Response

[{"links":[],
 "id":"anId",
 "definitionId":"aProcessDefinitionId",
 "businessKey":"aKey",
 "ended":false,
 "suspended":false}]

Get Instances Count (POST)

Query for the number of 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 /process-instance/count

Parameters

Request Body

A json object with the following properties:

Name Description
processInstanceIds Filter by a list of process instance ids. Must be a json array of Strings.
businessKey Filter by process instance business key.
processDefinitionId Filter by the process definition the instances run on.
processDefinitionKey Filter by the key of the process definition the instances run on.
superProcessInstance Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstance Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id.
active Only include active process instances. Values may be true or false.
suspended Only include suspended process instances. Values may be true or false.
variables A json array to only include process instances that have variables with certain values.
The array consists of objects with the three properties key, operator and value. key (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.
value may be String, Number or Boolean.
Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.

Result

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

Name Value Description
count Number The number of matching process instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /process-instance/count

Request body:

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

Response

{"count": 1}

Update/Delete Process Variables

Updates or deletes the variables of a process instance. Updates precede deletes. So if a variable is updated AND deleted, the deletion overrides the update.

Method

POST /process-instance/{id}/variables

Parameters

Path Parameters

Name Description
id The id of the process instance to set variables for.

Request Body

A json object with the following properties:

Name Description
modifications A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object. A variable value object has has the property value, which is the value to update, and type, which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date.
deletions An array of String keys of variables to be deleted.

Result

This method returns no content.

Response codes

Code Media type Description
204 application/json Request successful.
400 application/json The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.
500 application/json Update or delete could not be executed, for example because the process instance does not exist.

Example

Request

POST /process-instance/aProcessInstanceId/variables

Request body:

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

Response

Status 204. No content.

Activate/Suspend Process Instance

Activate or suspend a given process instance.

Method

PUT /process-instance/{id}/suspended

Parameters

Path Parameters

Name Description
id The id of the process instance to activate or suspend.

Request Body

A json object with the following properties:

Name Description
suspended A Boolean value which indicates whether to activate or suspend a given process instance. When the value is set to true, then the given process instance will be suspended and when the value is set to false, then the given process instance will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
404 application/json Process instance with given id does not exist. See the Introduction for the error response format.

Example

Request

PUT /process-instance/aProcessInstanceId/suspended

{"suspended" : true}

Response

Status 204. No content.

Put Single Process Variable

Sets a variable of a given process instance.

Method

PUT /process-instance/{id}/variables/{varId}

Parameters

Path Parameters

Name Description
id The id of the process instance to set the variable for.
varId The name of the variable to set.

Request Body

A json object with the following properties:

Name Description
value The value of the variable to set.
type The type of the variable to set. Valid types are Integer, Short, Long, Double, String, Boolean and Date.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.

Example

Request

PUT /process-instance/aProcessInstanceId/variables/aVarName

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

Response

Status 204. No content.

Get Single Task

Retrieves a single task by its id.

Method

GET /task/{id}

Parameters

Path Parameters

Name Description
id The id of the task to be retrieved.

Result

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

Name Value Description
id String The id of the task.
name String The tasks name.
assignee String The user assigned to this task.
created String The time the task was created. Format yyyy-MM-dd'T'HH:mm:ss.
due String The due date for the task. Format yyyy-MM-dd'T'HH:mm:ss.
delegationState String The delegation state of the task. Corresponds to the DelegationState enum in the engine. Possible values are RESOLVED and PENDING.
description String The task description.
executionId String The id of the execution the task belongs to.
owner String The owner of the task.
parentTaskId String The id of the parent task, if this task is a subtask.
priority Number The priority of the task.
processDefinitionId String The id of the process definition this task belongs to.
processInstanceId String The id of the process instance this task belongs to.
taskDefinitionKey String The task definition key.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Task with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /task/anId

Response

{"id":"anId",
"name":"aName",
"assignee":"anAssignee",
"created":"2013-01-23T13:42:42",
"due":"2013-01-23T13:42:43",
"delegationState":"RESOLVED",
"description":"aDescription",
"executionId":"anExecution",
"owner":"anOwner",
"parentTaskId":"aParentId",
"priority":42,
"processDefinitionId":"aProcDefId",
"processInstanceId":"aProcInstId",
"taskDefinitionKey":"aTaskDefinitionKey"}

Get Form Key

Retrieves the form key for a task. The form key corresponds to the FormData#formKey property in the engine. This key can be used to do task-specific form rendering in client applications. Additionally, the context path of the containing process application is returned.

Method

GET /task/{id}/form

Parameters

Path Parameters

Name Description
id The id of the task to retrieve the form for.

Result

A json object containing the form key.

Name Value Description
key String The for key for the task.
contextPath String The process application's context path the task belongs to. If the task does not belong to a process application deployment or a process definition at all, this property is not set.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Task with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /task/anId/form

Response

{"key":"aFormKey",
"contextPath":"http://localhost:8080/my-process-application/"}

Get Tasks

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

Method

GET /task

Parameters

Query Parameters

Name Description
processInstanceId Restrict to tasks that belong to process instances with the given id.
processInstanceBusinessKey Restrict to tasks that belong to process instances with the given business key.
processDefinitionId Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey Restrict to tasks that belong to a process definition with the given key.
processDefinitionName Restrict to tasks that belong to a process definition with the given name.
executionId Restrict to tasks that belong to an execution with the given id.
activityInstanceIdIn Only include tasks which belongs to one of the passed and comma-separated activity instance ids.
assignee Restrict to tasks that the given user is assigned to.
owner Restrict to tasks that the given user owns.
candidateGroup Only include tasks that are offered to the given group.
candidateUser Only include tasks that are offered to the given user.
involvedUser Only include tasks that the given user is involved in. A user is involved in a task if there exists an identity link between task and user (e.g., the user is the assignee).
unassigned If set to true, restricts the query to all tasks that are unassigned.
taskDefinitionKey Restrict to tasks that have the given key.
taskDefinitionKeyLike Restrict to tasks that have a key that has the parameter value as a substring.
name Restrict to tasks that have the given name.
nameLike Restrict to tasks that have a name with the given parameter value as substring.
description Restrict to tasks that have the given description.
descriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
priority Restrict to tasks that have the given priority.
maxPriority Restrict to tasks that have a lower or equal priority.
minPriority Restrict to tasks that have a higher or equal priority.
due Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
dueAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
dueBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
created Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid. Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero milliseconds.
createdAfter Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
createdBefore Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
delegationState Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED.
candidateGroups Restrict to tasks that are offered to any of the given candidate groups. Takes a comma-separated list of group names, so for example developers,support,sales.
active Only include active tasks. Values may be true or false.
suspended Only include suspended tasks. Values may be true or false.
taskVariables Only include tasks that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
processVariables Only include tasks that belong to process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are instanceId, dueDate, executionId, assignee, created, description, id, name and priority. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The task id.
name String The task name.
assignee String The assignee's id.
owner String The owner's id.
created String The date the task was created on. Has the format yyyy-MM-dd'T'HH:mm:ss.
due String The task's due date. Has the format yyyy-MM-dd'T'HH:mm:ss.
delegationState String The task's delegation state. Possible values are PENDING and RESOLVED.
description String The task's description.
executionId String The id of the execution the task belongs to.
parentTaskId String The id the parent task, if this task is a subtask.
priority Number The task's priority.
processDefinitionId String The id of the process definition the task belongs to.
processInstanceId String The id of the process instance the task belongs to.
taskDefinitionKey String The task's key.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /task?assignee=anAssignee&delegationState=RESOLVED&maxPriority=50

Response

[{"id":"anId",
 "name":"aName",
 "assignee":"anAssignee",
 "created":"2013-01-23T13:42:42",
 "due":"2013-01-23T13:42:43",
 "delegationState":"RESOLVED",
 "description":"aDescription",
 "executionId":"anExecution",
 "owner":"anOwner",
 "parentTaskId":"aParentId",
 "priority":42,
 "processDefinitionId":"aProcDefId",
 "processInstanceId":"aProcInstId",
 "taskDefinitionKey":"aTaskDefinitionKey"}]

Get Tasks Count

Get the number of tasks that fulfill a provided filter. Corresponds to the size of the result set when using the get tasks method.

Method

GET /task/count

Parameters

Query Parameters

Name Description
processInstanceId Restrict to tasks that belong to process instances with the given id.
processInstanceBusinessKey Restrict to tasks that belong to process instances with the given business key.
processDefinitionId Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey Restrict to tasks that belong to a process definition with the given key.
processDefinitionName Restrict to tasks that belong to a process definition with the given name.
executionId Restrict to tasks that belong to an execution with the given id.
activityInstanceIdIn Only include tasks which belongs to one of the passed and comma-separated activity instance ids.
assignee Restrict to tasks that the given user is assigned to.
owner Restrict to tasks that the given user owns.
candidateGroup Only include tasks that are offered to the given group.
candidateUser Only include tasks that are offered to the given user.
involvedUser Only include tasks that the given user is involved in. A user is involved in a task if there exists an identity link between task and user (e.g., the user is the assignee).
unassigned If set to true, restricts the query to all tasks that are unassigned.
taskDefinitionKey Restrict to tasks that have the given key.
taskDefinitionKeyLike Restrict to tasks that have a key that has the parameter value as a substring.
name Restrict to tasks that have the given name.
nameLike Restrict to tasks that have a name with the given parameter value as substring.
description Restrict to tasks that have the given description.
descriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
priority Restrict to tasks that have the given priority.
maxPriority Restrict to tasks that have a lower or equal priority.
minPriority Restrict to tasks that have a higher or equal priority.
due Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
dueAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
dueBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
created Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid. Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero milliseconds.
createdAfter Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
createdBefore Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
delegationState Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED.
candidateGroups Restrict to tasks that are offered to any of the given candidate groups. Takes a comma-separated list of group names, so for example developers,support,sales.
active Only include active tasks. Values may be true or false.
suspended Only include suspended tasks. Values may be true or false.
taskVariables Only include tasks that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
processVariables Only include tasks that belong to process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.

Result

A json object with a single count property.

Name Value Description
count Number The number of tasks that fulfill the query criteria.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /task/count?assignee=anAssignee&delegationState=RESOLVED&maxPriority=50

Response

{"count":1}

Set Assignee

Change the assignee of a task to a specific user.

Note: The difference with claim a task is that this method does not check whether the task does already have a user assigned to it.

Method

POST /task/{id}/assignee

Parameters

Path Parameters

Name Description
id The id of the task to set the assignee.

Request Body

A json object with the following properties:

Name Description
userId The id of the user that will be the assignee of the task.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
500 application/json Task with given id does not exist or setting the assignee was not successful. See the Introduction for the error response format.

Example

Request

POST /task/anId/assignee

Request body:

{"userId": "aUserId"}

Response

Status 204. No content.

Claim Task

Claim a task for a specific user.

Note: The difference with set a assignee is that here a check is done if the task already has a user assigned to it.

Method

POST /task/{id}/claim

Parameters

Path Parameters

Name Description
id The id of the task to claim.

Request Body

A json object with the following properties:

Name Description
userId The id of the user that claims the task.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
500 application/json Task with given id does not exist or claiming was not successful. See the Introduction for the error response format.

Example

Request

POST /task/anId/claim

Request body:

{"userId": "aUserId"}

Response

Status 204. No content.

Complete Task

Complete a task and update process variables.

Method

POST /task/{id}/complete

Parameters

Path Parameters

Name Description
id The id of the task to complete.

Request Body

A json object with the following properties:

Name Description
variables A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object. A variable value object has has the property value, which is the value to update, and type, which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. This parameter is optional and may be left out.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.
500 application/json If the task does not exist or the corresponding process instance could not be resumed successfully. See the Introduction for the error response format.

Example

Request

POST /task/anId/complete

Request body:

{"variables":
    {"aVariable": {"value": "aStringValue"},
    "anotherVariable": {"value": 42},
    "aThirdVariable": {"value": true}}
}

Response

Status 204. No content.

Delegate Task

Delegate a task to another user.

Method

POST /task/{id}/delegate

Parameters

Path Parameters

Name Description
id The id of the task to delegate.

Request Body

A json object with the following properties:

Name Description
userId The id of the user that the task should be delegated to.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
500 application/json If the task does not exist or delegation was not successful. See the Introduction for the error response format.

Example

Request

POST /task/anId/delegate

Request body:

{"userId": "aUserId"}

Response

Status 204. No content.

Get Tasks (POST)

Query for tasks that fulfill a given filter. 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 /task

Parameters

Query Parameters

Name Description
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Request Body

A json object with the following properties:

Name Description
processInstanceId Restrict to tasks that belong to process instances with the given id.
processInstanceBusinessKey Restrict to tasks that belong to process instances with the given business key.
processDefinitionId Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey Restrict to tasks that belong to a process definition with the given key.
processDefinitionName Restrict to tasks that belong to a process definition with the given name.
executionId Restrict to tasks that belong to an execution with the given id.
activityInstanceIdIn Only include tasks which belongs to one of the passed activity instance ids.
assignee Restrict to tasks that the given user is assigned to.
owner Restrict to tasks that the given user owns.
candidateGroup Only include tasks that are offered to the given group.
candidateUser Only include tasks that are offered to the given user.
involvedUser Only include tasks that the given user is involved in. A user is involved in a task if there exists an identity link between task and user (e.g., the user is the assignee).
unassigned If set to true, restricts the query to all tasks that are unassigned.
taskDefinitionKey Restrict to tasks that have the given key.
taskDefinitionKeyLike Restrict to tasks that have a key that has the parameter value as a substring.
name Restrict to tasks that have the given name.
nameLike Restrict to tasks that have a name with the given parameter value as substring.
description Restrict to tasks that have the given description.
descriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
priority Restrict to tasks that have the given priority.
maxPriority Restrict to tasks that have a lower or equal priority.
minPriority Restrict to tasks that have a higher or equal priority.
dueDate Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
dueAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
dueBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
createdOn Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid. Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero milliseconds.
createdAfter Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
createdBefore Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
delegationState Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED.
candidateGroups Restrict to tasks that are offered to any of the given candidate groups. Takes a json array of group names, so for example ["developers", "support", "sales"].
active Only include active tasks. Values may be true or false.
suspended Only include suspended tasks. Values may be true or false.
taskVariables A json array to only include tasks that have variables with certain values.
The array consists of json objects with three properties name, operator and value. name is the variable name, op is the comparison operator to be used and value the variable value.
value may be of type String, Number or Boolean.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
processVariables A json array to only include tasks that belong to a process instance with variables with certain values.
The array consists of json objects with three properties name, operator and value. name is the variable name, op is the comparison operator to be used and value the variable value.
value may be of type String, Number or Boolean.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
sortBy Sort the results lexicographically by a given criterion. Valid values are instanceId, dueDate, executionId, assignee, created, description, id, name and priority. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
id String The task id.
name String The task name.
assignee String The assignee's id.
owner String The owner's id.
created String The date the task was created on. Has the format yyyy-MM-dd'T'HH:mm:ss.
due String The task's due date. Has the format yyyy-MM-dd'T'HH:mm:ss.
delegationState String The task's delegation state. Possible values are PENDING and RESOLVED
description String The task's description.
executionId String The id of the execution the task belongs to.
parentTaskId String The id the parent task, if this task is a subtask.
priority Number The task's priority.
processDefinitionId String The id of the process definition the task belongs to.
processInstanceId String The id of the process instance the task belongs to.
taskDefinitionKey String The task's key.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /task

Request body:

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

Response

[{"id":"anId",
 "name":"aName",
 "assignee":"anAssignee",
 "created":"2013-01-23T13:42:42",
 "due":"2013-01-23T13:42:43",
 "delegationState":"RESOLVED",
 "description":"aDescription",
 "executionId":"anExecution",
 "owner":"anOwner",
 "parentTaskId":"aParentId",
 "priority":10,
 "processDefinitionId":"aProcDefId",
 "processInstanceId":"aProcInstId",
 "taskDefinitionKey":"aTaskDefinitionKey"}]

Get Tasks Count (POST)

Get the number of tasks that fulfill the given filter. Corresponds to the size of the result set of the get tasks (POST) method and takes the same parameters.

Method

POST /task/count

Parameters

Request Body

A json object with the following properties:

Name Description
processInstanceId Restrict to tasks that belong to process instances with the given id.
processInstanceBusinessKey Restrict to tasks that belong to process instances with the given business key.
processDefinitionId Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey Restrict to tasks that belong to a process definition with the given key.
processDefinitionName Restrict to tasks that belong to a process definition with the given name.
executionId Restrict to tasks that belong to an execution with the given id.
activityInstanceIdIn Only include tasks which belongs to one of the passed activity instance ids.
assignee Restrict to tasks that the given user is assigned to.
owner Restrict to tasks that the given user owns.
candidateGroup Only include tasks that are offered to the given group.
candidateUser Only include tasks that are offered to the given user.
involvedUser Only include tasks that the given user is involved in. A user is involved in a task if there exists an identity link between task and user (e.g., the user is the assignee).
unassigned If set to true, restricts the query to all tasks that are unassigned.
taskDefinitionKey Restrict to tasks that have the given key.
taskDefinitionKeyLike Restrict to tasks that have a key that has the parameter value as a substring.
name Restrict to tasks that have the given name.
nameLike Restrict to tasks that have a name with the given parameter value as substring.
description Restrict to tasks that have the given description.
descriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
priority Restrict to tasks that have the given priority.
maxPriority Restrict to tasks that have a lower or equal priority.
minPriority Restrict to tasks that have a higher or equal priority.
dueDate Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
dueAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
dueBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
createdOn Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid. Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero milliseconds.
createdAfter Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
createdBefore Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, so for example 2013-01-23T14:42:45 is valid.
delegationState Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED.
candidateGroups Restrict to tasks that are offered to any of the given candidate groups. Takes a json array of group names, so for example ["developers", "support", "sales"].
active Only include active tasks. Values may be true or false.
suspended Only include suspended tasks. Values may be true or false.
taskVariables A json array to only include tasks that have variables with certain values.
The array consists of json objects with three properties name, operator and value. name is the variable name, op is the comparison operator to be used and value the variable value.
value may be of type String, Number or Boolean.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
processVariables A json array to only include tasks that belong to a process instance with variables with certain values.
The array consists of json objects with three properties name, operator and value. name is the variable name, op is the comparison operator to be used and value the variable value.
value may be of type String, Number or Boolean.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.

Result

A json object with a single count property.

Name Value Description
count Number The number of tasks that fulfill the query criteria.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /task/count

Request body:

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

Response

{"count":1}

Resolve Task

Resolve a task and update execution variables.

Method

POST /task/{id}/resolve

Parameters

Path Parameters

Name Description
id The id of the task to resolve.

Request Body

A json object with the following properties:

Name Description
variables A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object. A variable value object has has the property value, which is the value to update, and type, which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. This parameter is optional and may be left out.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format.
500 application/json If the task does not exist or the corresponding process instance could not be resumed successfully. See the Introduction for the error response format.

Example

Request

POST /task/anId/resolve

Request body:

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

Response

Status 204. No content.

Unclaim Task

Resets a task's assignee. If successful, the task is not assigned to a user.

Method

POST /task/{id}/unclaim

Parameters

Path Parameters

Name Description
id The id of the task to unclaim.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Task with given id does not exist. See the Introduction for the error response format.

Example

Request

POST /task/anId/unclaim

Response

Status 204. No content.

Delete User

Deletes a user by id.

Method

DELETE /user/{id}

Parameters

Path Parameters

Name Description
id The id of the user to be deleted.

Request Body

Empty.

Result

This method returns no content.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json User cannot be found. See the Introduction for the error response format.

Example

Request

DELETE /user/jonny1

Response

Status 204. No content.

Get a User's Profile

Retrieves a single user's profile.

Method

GET /user/{id}/profile

Parameters

Path Parameters

Name Description
id The id of the user to be retrieved.

Result

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

Name Value Description
id String The id of the user.
firstName String The firstname of the user.
lastName String The lastname of the user.
email String The email of the user.
links Object A json array containing links to interact with the instance. The links contain only operations that the currently authenticated user is authorized to perform.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Execution with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /user/jonny1/profile

Response

Status 200.

{"id":"jonny1",
  "firstName":"John",
  "lastName":"Doe",
  "email":"anEmailAddress"}

Get Users

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

Method

GET /user

Parameters

Query Parameters

Name Description
id Filter by the id of the user.
firstName Filter by the firstname of the user.
firstNameLike Filter by the firstname that the parameter is a substring of.
lastName Filter by the lastname of the user.
lastNameLike Filter by the lastname that the parameter is a substring of.
email Filter by the email of the user.
emailLike Filter by the email that the parameter is a substring of.
memberOfGroup Filter for users which are members of a group.
sortBy Sort the results lexicographically by a given criterion. Valid values are userId, firstName, lastName and email. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
id String The id of the user.
firstName String The firstname of the user.
lastName String The lastname of the user.
email String The email of the user.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy is specified. See the Introduction for the error response format.

Example

Request

GET /user?firstName=John

Response

Status 200.

[{"id":"jonny1",
  "firstName":"John",
  "lastName":"Doe",
  "email":"anEmailAddress"},
 {"id":"jonny2",
  "firstName":"John",
  "lastName":"Smoe",
  "email":"anEmailAddress"}]

Get Users Count

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

Method

GET /user/count

Parameters

Query Parameters

Name Description
id Filter by the id of the user.
firstName Filter by the firstname of the user.
firstNameLike Filter by the firstname that the parameter is a substring of.
lastName Filter by the lastname of the user.
lastNameLike Filter by the lastname that the parameter is a substring of.
email Filter by the email of the user.
emailLike Filter by the email that the parameter is a substring of.
memberOfGroup Filter for users which are members of a group.

Result

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

Name Value Description
count Number The number of matching users.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy is specified. See the Introduction for the error response format.

Example

Request

GET /user/count?firstName=John

Response

Status 200.

{"count": 2}

User Resource Options

The /user resource supports two custom OPTIONS requests, one for the resource as such and one for individual user instances. The options request allows checking for the set of available operations that the currently authenticated user can perform on the /user 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 /user for available interactions on resource OPTIONS /user/{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

Name Value Description
method String The HTTP method to use for the interaction.
href String The interaction URL
rel String The relation of the interaction (i.e., a symbolic name representing the nature of the interaction). Examples: create, delete ...

Response codes

Code Media type Description
200 application/json Request successful.

Example

Request

OPTIONS /user/aUserId

Response

Status 200.

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

Create user

Create a new user.

Method

POST /user/create

Parameters

Request Body

A json object with the following properties:

Name Type Description
profile Array A json object containing variable key-value pairs. The object contains the following properties: id (String), firstName (String), lastName (String) and email (String).
credentials Array A json object containing variable key-value pairs. The object contains the following properties: password (String).

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
500 application/json The user could not be created due to an internal server error. See the Introduction for the error response format.

Example

Request

POST /user/create

Request body:

{"profile": 
  {"id": "jonny1",
  "firstName":"John",
  "lastName":"Doe",
  "email":"aNewEmailAddress"},
"credentials": 
  {"password":"s3cret"}
}

Response

Status 204. No content.

Update a user's credentials

Updates a user's credentials (password).

Method

PUT /user/{id}/credentials

Parameters

Request Body

A json object with the following properties:

Name Type Description
password String The user's new password.
authenticatedUserPassword String The password of the authenticated user who changes the password of the user (i.e., the user with passed id as path parameter).

Result

Empty.

Response codes

Code Media type Description
204 Empty Request successful.
400 Empty If the authenticated user password does not match.
404 application/json If the corresponding user cannot be found
500 application/json The user could not be created due to an internal server error. See the Introduction for the error response format.

Example

Request

PUT /user/jonny1/credentials

Request body:

{"password":"s3cr3t", "authenticatedUserPassword": "demo"}

Response

None.

Update User Profile

Updates the profile information of an already existing user.

Method

PUT /user/{id}/profile

Parameters

Path Parameters

Name Type Description
id String The id of the user.

Request Body

A json object with the following properties:

Name Type Description
id String The id of the user.
firstName String The firstname of the user.
lastName String The lastname of the user.
email String The email of the user.

Result

Empty.

Response codes

Code Media type Description
204 None Request successful.
404 application/json If the user with the requested Id cannot be found.
500 application/json The user could not be updated due to an internal server error. See the Introduction for the error response format.

Example

Request

PUT /user/jonny1/profile

Request body:

{"id":"jonny1",
  "firstName":"John",
  "lastName":"Doe",
  "email":"aNewEmailAddress"}

Response

Empty.

Get Variable Instances

Query for variable instances that fulfill given parameters. Parameters may be the properties of variable instances, such as the name or type. The size of the result set can be retrieved by using the get variable instances count method.

Method

GET /variable-instance

Parameters

Query Parameters

Name Description
variableName Filter by variable instance name.
variableNameLike Filter by the variable instance name. The parameter can include the wildcard % to express like-strategy such as: starts with (%name), ends with (name%) or contains (%name%).
processInstanceIdIn Only include variable instances which belongs to one of the passed and comma-separated process instance ids.
executionIdIn Only include variable instances which belongs to one of the passed and comma-separated execution ids.
taskIdIn Only include variable instances which belongs to one of the passed and comma-separated task ids.
activityInstanceIdIn Only include variable instances which belongs to one of the passed and comma-separated activity instance ids.
variableValues Only include variable instances that have the certain values. Value filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are variableName, variableType and activityInstanceId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
name String The name of the variable instance.
type String The simple class name of the variable instance.
value String/Number/Boolean/Object Object serialization uses Jackson's POJO/bean property introspection feature.
processInstanceId String The id of the process instance that this variable instance belongs to.
executionId String The id of the execution that this variable instance belongs to.
taskId String The id of the task that this variable instance belongs to.
activityInstanceId String The id of the activity instance that this variable instance belongs to.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /variable-instance?processInstanceIdIn=aProcessInstanceId,anotherProcessInstanceId&variableValues=amount_gteq_5,amount_lteq_200

Response

[
  {
    "name": "amount",
    "type": "integer",
    "value": 5,
    "processInstanceId": "aProcessInstanceId",
    "executionId": "b68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726"
  },
  {
    "name": "amount",
    "type": "integer",
    "value": 15,
    "processInstanceId": "aProcessInstanceId",
    "executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726"
  },
  {
    "name": "amount",
    "type": "integer",
    "value": 150,
    "processInstanceId": "anotherProcessInstanceId",
    "executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_2:b68b71ca-e310-11e2-beb0-f0def1557726"
  }      
]

Get Variable Instances Count

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

Method

GET /variable-instance/count

Parameters

Query Parameters

Name Description
variableName Filter by variable instance name.
variableNameLike Filter by the variable instance name. The parameter can include the wildcard % to express like-strategy such as: starts with (%name), ends with (name%) or contains (%name%).
processInstanceIdIn Only include variable instances which belongs to one of the passed and comma-separated process instance ids.
executionIdIn Only include variable instances which belongs to one of the passed and comma-separated execution ids.
taskIdIn Only include variable instances which belongs to one of the passed and comma-separated task ids.
activityInstanceIdIn Only include variable instances which belongs to one of the passed and comma-separated activity instance ids.
variableValues Only include variable instances that have the certain values. Value filtering expressions are comma-separated and are structured as follows:
A valid parameter value has the form key_operator_value. key is the variable name, op is the comparison operator to be used and value the variable value.
Note: Values are always treated as String objects on server side.

Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are variableName, variableType and activityInstanceId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Result

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

Name Value Description
count Number The number of matching variable instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /variable-instance/count?processInstanceIdIn=aProcessInstanceId,anotherProcessInstanceId&variableValues=amount_gteq_5,amount_lteq_200

Response

{"count": 3}

Get Variable Instances (POST)

Query for variable instances 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 variable instances of types String, Number or Boolean.

Method

POST /variable-instance

Parameters

Query Parameters

Name Description
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Request Body

A json object with the following properties:

Name Description
variableName Filter by variable instance name.
variableNameLike Filter by the variable instance name. The parameter can include the wildcard % to express like-strategy such as: starts with (%name), ends with (name%) or contains (%name%).
processInstanceIdIn Only include variable instances which belongs to one of the passed process instance ids.
executionIdIn Only include variable instances which belongs to one of the passed execution ids.
taskIdIn Only include variable instances which belongs to one of the passed task ids.
activityInstanceIdIn Only include variable instances which belongs to one of the passed activity instance ids.
variableValues A json array to only include variable instances that have the certain values.
The array consists of objects with the three properties name, operator and value. name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.
value may be String, Number or Boolean.
Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
sortBy Sort the results lexicographically by a given criterion. Valid values are variableName, variableType and activityInstanceId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
name String The name of the variable instance.
type String The simple class name of the variable instance.
value String/Number/Boolean/Object Object serialization uses Jackson's POJO/bean property introspection feature.
processInstanceId String The id of the process instance that this variable instance belongs to.
executionId String The id of the execution that this variable instance belongs to.
taskId String The id of the task that this variable instance belongs to.
activityInstanceId String The id of the activity instance that this variable instance belongs to.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /variable-instance

Request body:

{"variableValuess": 
    [{"name": "amount",
     "operator": "gteq",
     "value": "5"
    },
    {"name": "amount",
     "operator": "lteq",
     "value": 200}],
"processInstanceIdIn": [ "aProcessInstanceId", "anotherProcessInstanceId" ]}

Response

[
  {
    "name": "amount",
    "type": "integer",
    "value": 5,
    "processInstanceId": "aProcessInstanceId",
    "executionId": "b68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726"
  },
  {
    "name": "amount",
    "type": "integer",
    "value": 15,
    "processInstanceId": "aProcessInstanceId",
    "executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726"
  },
  {
    "name": "amount",
    "type": "integer",
    "value": 150,
    "processInstanceId": "anotherProcessInstanceId",
    "executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_2:b68b71ca-e310-11e2-beb0-f0def1557726"
  }      
]

Get Variable Instances Count (POST)

Query for the number of variable instances 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 /variable-instance/count

Parameters

Request Body

A json object with the following properties:

Name Description
variableName Filter by variable instance name.
variableNameLike Filter by the variable instance name. The parameter can include the wildcard % to express like-strategy such as: starts with (%name), ends with (name%) or contains (%name%).
processInstanceIdIn Only include variable instances which belongs to one of the passed process instance ids.
executionIdIn Only include variable instances which belongs to one of the passed execution ids.
taskIdIn Only include variable instances which belongs to one of the passed task ids.
activityInstanceIdIn Only include variable instances which belongs to one of the passed activity instance ids.
variableValues A json array to only include variable instances that have the certain values.
The array consists of objects with the three properties name, operator and value. name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.
value may be String, Number or Boolean.
Valid operator values are: eq - equals; neq - not equals; gt - greater than; gteq - greater than or equals; lt - lower than; lteq - lower than or equals; like.
sortBy Sort the results lexicographically by a given criterion. Valid values are variableName, variableType and activityInstanceId. Must be used in conjunction with the sortOrder parameter.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.

Result

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

Name Value Description
count Number The number of matching variable instances.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /variable-instance/count

Request body:

{"variableValuess": 
    [{"name": "amount",
     "operator": "gteq",
     "value": "5"
    },
    {"name": "amount",
     "operator": "lteq",
     "value": 200}],
"processInstanceIdIn": [ "aProcessInstanceId", "anotherProcessInstanceId" ]}

Response

{"count": 3}