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 where {name} is the name of the process engine as returned by ProcessEngine#getName(), e.g., /engine/myEngineName/task.

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 necessarily the case. One such case we are aware of is with some types of RESTEasy deployments:

RESTEasy allows deployment of 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 distribution, 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 is 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 (i.e., it is globally visible) process engine 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 to your project as a Maven dependency.

    Please import the Camunda BOM to ensure correct versions for every Camunda project.

    <dependency>
      <groupId>org.camunda.bpm</groupId>
      <artifactId>camunda-engine-rest</artifactId>
      <classifier>classes</classifier>
    </dependency>
  • Add the REST resources that you need to your JAX-RS application. Example:

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

    CamundaRestResources.getResourceClasses() contains two JAX-RS resources that serve as the entry points. One of these (org.camunda.bpm.engine.rest.impl.NamedProcessEngineRestServiceImpl) provides all of the REST resources listed in this document on paths beginning with /engine/{name} while the other (org.camunda.bpm.engine.rest.impl.DefaultProcessEngineRestServiceImpl) provides access to the default engine's resources on the root path /.

    To restrict the exposed REST resources to specific types (e.g. only process-definition-related methods), a subclass of org.camunda.bpm.engine.rest.impl.AbstractProcessEngineRestServiceImpl can be implemented and registered with the JAX-RS application. Such a subclass can control which resources get exposed by offering JAX-RS-annotated methods. See the sources of NamedProcessEngineRestServiceImpl and DefaultProcessEngineRestServiceImpl for an example. Note: The path to a subresource should always match the path defined in the subresource's interface.

    The configuration class JacksonConfigurator is required to correctly configure the serialization of date fields. 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 / Wildfly 8 these should be automatically added as an implicit module dependency.

    For proper exception responses of the format as described in the Introduction, it is necessary 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). To do this, you must 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 that the class org.camunda.bpm.BpmPlatform provides.

Hypertext Application Language (HAL)

The REST API provides some resources in an additional media type. The HAL media type application/hal+json describes a format which contains links and information about other resources. This allows us to embed the process definition or assignee of a task directly into the response, which in turn reduces the number of necessary requests to gather all information about a single task or a list of tasks.

In order to interact with HAL, you have to set application/hal+json as Accept header. The response of a HAL request has always the following structure:

{
  "_links" : {},
  "_embedded" : {}
}

The property _links contains relational links that give an easy way to navigate between associated resources. A _links property contains at least a self relational link. The property _embedded includes other linked resources in the representing resource. Each embedded resource will be structured as a HAL resource.

Example: Resource

Request

GET /task/a-task-id

Request Header:

Accept: application/hal+json

Response

{
  "_links" : {
    "self": {
      "href": "/task/a-task-id"
    },
    "assignee": {
      "href": "/user/demo"
    },
    ...
  },
  "_embedded" : {
    "group" : [{
      "_links" : {
        "self" : {
          "href" : "/group/management"
        }
      },
      "_embedded" : null,
      "id" : "management",
      ...
    }],
    "processDefinition" : [ {...}, {...} ],
    ...
  },
  "id" : "a-task-id",
  "name": "Assign Approver",
  "assignee": "demo",
  ...
}

Example: Collection

Request

GET /task

Request Header:

Accept: application/hal+json

Response

{
  "_links" : {
    "self": {
      "href": "/task"
    }
  },
  "_embedded" : {
    "assignee" : [{
      "_links" : {
        "self" : {
          "href" : "/user/demo"
        }
      },
      "_embedded" : null,
      id: "demo",
      ...
    }],
    "processDefinition" : [ {...} ],
    "task" : [{
      "_links" : {
        "self": {
          "href": "/task/a-task-id"
        },
        "assignee": {
          "href": "/user/demo"
        },
        ...
      },
      "_embedded" : {
        "variable" : [ {...}, {...} ]
      },
      "id" : "a-task-id",
      "name": "Assign Approver",
      "assignee": "demo",
      ...
    }, {
      ...
    }]
  },
  "count" : 2
}

Caching of HAL relations

During the generation of a HAL response, linked resources are resolved to embed them. Some of these resolved resources, like process definitions or users, are rarely modified. Also, if user information is stored in an external system (such as LDAP), every request will access this external system which is an unnecessary overhead. To reduces such expensive requests, the REST API can be configured to use a cache to temporary store such relations.

This caching can be configured in the web.xml file of the REST API (or the Camunda Web Application in case the REST API is embedded into the Camunda Web Application).

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  <!-- ... -->

  <listener>
    <listener-class>org.camunda.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
  </listener>

  <context-param>
    <param-name>org.camunda.bpm.engine.rest.hal.cache.config</param-name>
    <param-value>
      {
        "cacheImplementation": "org.camunda.bpm.engine.rest.hal.cache.DefaultHalResourceCache",
        "caches": {
          "org.camunda.bpm.engine.rest.hal.user.HalUser": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "org.camunda.bpm.engine.rest.hal.group.HalGroup": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "org.camunda.bpm.engine.rest.hal.processDefinition.HalProcessDefinition": {
            "capacity": 100,
            "secondsToLive": 600
          }
        }
      }
    </param-value>
  </context-param>

  <!-- ... -->

</web-app>

The HalRelationCacheBootstrap Listener

To bootstrap the caching, the HalRelationCacheBootstrap context listener is used:

<listener>
  <listener-class>org.camunda.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
</listener>

It is configured by the context parameter org.camunda.bpm.engine.rest.hal.cache.config. The configuration is provided as JSON and consists of two properties:

Property Description
cacheImplementation The class which is used as cache. The class has to implement the org.camunda.bpm.engine.rest.cache.Cache interface. A simple default implementation is provided by the org.camunda.bpm.engine.rest.hal.cache.DefaultHalResourceCache class.
caches A JSON object to specify which HAL relations should be cached. Every HAL relation cache is configured separately and identified by the HalResource class to cache. The possible configuration parameters depend on the cache implementation and have to be available as setters on the implementation class.

DefaultHalResourceCache Configuration Options

The simple default cache implementation DefaultHalResourceCache provides following configuration options:

Property Description
capacity The number of maximal cache entries.
secondsToLive The number of seconds a cache entry is valid. If a cache entry is expired, it is removed and resolved again.

List of Resources which support Caching

  • Case Definition: org.camunda.bpm.engine.rest.hal.caseDefinition.HalCaseDefinition
  • Group: org.camunda.bpm.engine.rest.hal.group.HalGroup
  • Identity Links (of a Task): org.camunda.bpm.engine.rest.hal.identitylink.HalIdentityLink
  • Process Definition: org.camunda.bpm.engine.rest.hal.processDefinition.HalProcessDefinition
  • Task: org.camunda.bpm.engine.rest.hal.task.HalTask
  • User: org.camunda.bpm.engine.rest.hal.user.HalUser

Variables in the REST API

In the REST API, process variables are represented by JSON objects of the following form:

{
  "type": "String",
  "value": "Some value",
  "valueInfo": {}

}

The REST API supports the Value Types supported by the process engine.

Capitalization of Type Names

In the REST API, the type names start with a capital letter, i.e., String instead of string.

Serialized and Deserialized Object Values

Object Values are instances of (non primitive) Java types. When working with the REST API, it is generally advisable to work with the serialized value of a variable. In that case the value is retrieved from the database and directly returned in the http response. If the client you are building is not a Java Applications by itself, make sure you use a text-based serialization dataformat (such as XML or JSON).

In order to retrieve the serialized form of a variable, use the deserializeValues=false GET parameter.

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.

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-separated list of userIds
groupIdIn Filter by a comma-separated 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 retrieve 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 you to check for the set of available operations that the currently authenticated user can perform on the /authorization resource. Whether the user can perform an operation or not may depend on various factors, including the users authorizations to interact with this resource and the internal 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 (ie. 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 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

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
403 application/json The authenticated user is unauthorized to update this resource. See the Introduction for the error response format.
404 application/json 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

Status 204. No content.

Get Single Case Definition

Retrieves a single case definition according to the CaseDefinition interface in the engine.

Method

GET /case-definition/{id}

GET /case-definition/key/{key} (returns the latest version of case definition)

Parameters

Path Parameters

Name Description
id The id of the case definition to be retrieved.
key The key of the case definition (the latest version thereof) to be retrieved.

Result

A JSON object corresponding to the CaseDefinition interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the case definition.
key String The key of the case definition, i.e. the id of the CMMN 2.0 XML case definition.
category String The category of the case definition.
name String The name of the case definition.
version Number The version of the case definition that the engine assigned to it.
resource String The file name of the case definition.
deploymentId String The deployment id of the case definition.

Response codes

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

Example

Request

GET /case-definition/aCaseDefinitionId

GET /case-definition/key/aCaseDefinitionKey

Response

{
  "id":"aCaseDefinitionId",
  "key":"aCaseDefinitionKey",
  "category":"aCategory",
  "name":"aName",
  "version":42,
  "resource":"aResourceName",
  "deploymentId":"aDeploymentId"
}

Get Case Diagram

Retrieves the diagram of a case definition.

Method

GET /case-definition/{id}/diagram

GET /case-definition/key/{key}/diagram (returns the diagram for the latest version of the case definition)

Parameters

Path Parameters

Name Description
id The id of the case definition.
key The key of the case definition (the latest version thereof) to be retrieved.

Result

The image diagram of this case.

Response codes

Code Media type Description
200 image/png, image/gif, ... (defaults to application/octet-stream if the file suffix is unknown Request successful.
204 The case definition doesn't have an associated diagram.
400 application/json The path parameter "key" has no value or the case definition with given id does not exist. See the Introduction for the error response format.
404 application/json Case definition with given id or key does not exist. See the Introduction for the error response format.

Example

Request

GET /case-definition/invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c/diagram

GET /case-definition/key/invoice/diagram

Get Case Definitions

Query for case definitions that fulfill given parameters. Parameters may be the properties of case 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 /case-definition

Parameters

Query Parameters

Name Description
caseDefinitionId Filter by case definition id.
name Filter by case definition name.
nameLike Filter by case definition names that the parameter is a substring of.
deploymentId Filter by the deployment the id belongs to.
key Filter by case definition key, i.e. the id in the CMMN 1.0 XML. Exact match.
keyLike Filter by case definition keys that the parameter is a substring of.
category Filter by case definition category. Exact match.
categoryLike Filter by case definition categories that the parameter is a substring of.
version Filter by case definition version.
latest Only include those case definitions that are latest versions. Values may be true or false.
resourceName Filter by the name of the case definition resource. Exact match.
resourceNameLike Filter by names of those case definition resources that the parameter is a substring of.
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 case definition objects. Each case definition object has the following properties:

Name Value Description
id String The id of the case definition.
key String The key of the case definition, i.e. the id of the CMMN 1.0 XML case definition.
category String The category of the case definition.
name String The name of the case definition.
version Number The version of the case definition that the engine assigned to it.
resource String The file name of the case definition.
deploymentId String The deployment id of the case definition.

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 /case-definition?keyLike=Key&sortBy=category&sortOrder=asc

Response

[
  {
    "id":"aCaseDefinitionId",
    "key":"aKey",
    "category":"aCategory",
    "name":"aName",
    "version":2,
    "resource":"aResourceName",
    "deploymentId":"aDeploymentId"
  }
]

Get Case Definitions Count

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

Method

GET /case-definition/count

Parameters

Query Parameters

Name Description
caseDefinitionId Filter by case definition id.
name Filter by case definition name.
nameLike Filter by case definition names that the parameter is a substring of.
deploymentId Filter by the deployment the id belongs to.
key Filter by case definition key, i.e. the id in the CMMN 1.0 XML. Exact match.
keyLike Filter by case definition keys that the parameter is a substring of.
category Filter by case definition category. Exact match.
categoryLike Filter by case definition categories that the parameter is a substring of.
version Filter by case definition version.
latest Only include those case definitions that are latest versions. Values may be true or false.
resourceName Filter by the name of the case definition resource. Exact match.
resourceNameLike Filter by names of those case definition resources that the parameter is a substring of.

Result

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

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

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 /case-definition/count?keyLike=Key&version=2

Response

{
  "count": 1
}

Get CMMN 1.0 XML

Retrieves the CMMN 1.0 XML of this case definition.

Method

GET /case-definition/{id}/xml

GET /case-definition/key/{key}/xml (returns the XML for the latest version of case definition)

Parameters

Path Parameters

Name Description
id The id of the case definition.
key The key of the case definition (the latest version thereof) to be retrieved.

Result

A JSON object containing the id of the case definition and the CMMN 1.0 XML.

Name Value Description
id String The id of the case definition.
cmmnXml String An escaped XML string containing the XML that this case 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 The path parameter "key" has no value.
. See the Introduction for the error response format.
404 application/json Case definition with given id or key does not exist. See the Introduction for the error response format.

Example

Request

GET /case-definition/aCaseDefinitionId/xml

GET /case-definition/key/aCaseDefinitionKey/xml

Response

{
  "id":"aCaseDefinitionId",
  "cmmnXml":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\r\n<definitions xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
  ...
  <humanTask id=\"aHumanTask\" name=\"A HumanTask\">\r\n
  ..."
}

Create Case Instance

Instantiates a given case definition. Case variables and business key may be supplied in the request body.

Method

POST /case-definition/{id}/create

POST /case-definition/key/{key}/create (creates the latest version of the case definition)

Parameters

Path Parameters

Name Description
id The id of the case definition to be retrieved.
key The key of the case definition (the latest version thereof) to be retrieved.

Request Body

A JSON object with the following properties:

Name Description
variables A json object containing the variables the case instance 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.
businessKey The business key the case instance is to be initialized with. The business key uniquely identifies the case instance in the context of the given case definition.

Result

A JSON object representing the newly created case instance. Properties are:

Name Value Description
id String The id of the case instance.
caseDefinitionId String The id of the case definition this case instance belongs to.
businessKey String The business key of the case instance.
active Boolean A flag indicating whether the case instance is active or not.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json The path parameter "key" has no value.
The case instance could not be created due to an invalid variable value, for example if 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.
403 application/json The case execution cannot be instantiated because of CMMN restrictions. See the Introduction for the error response format.
404 application/json The case instance could not be created due to a nonexistent case definition. See the Introduction for the error response format.
500 application/json The case instance could not be created successfully. See the Introduction for the error response format.

Example

Request

POST /case-definition/aCaseDefinitionId/create

POST /case-definition/key/aCaseDefinitionKey/create

Request body:

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

Response

{
  "links":[{"method": "GET", "href":"http://localhost:8080/rest-test/process-instance/anId","rel":"self"}],
  "id":"anId",
  "caseDefinitionId":"aCaseDefinitionId",
  "businessKey":"myBusinessKey",
  "active":true
}

Delete Local Case Execution Variable

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

Method

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

Parameters

Path Parameters

Name Description
id The id of the case 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 /case-execution/aCaseExecutionId/localVariables/aVarName

Response

Status 204. No content.

Delete Single Case Execution Variable

Deletes a variable of a given case execution.

Method

DELETE /case-execution/{id}/variables/{varId}

Parameters

Path Parameters

Name Description
id The id of the case 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 /case-execution/aCaseExecutionId/variables/aVarName

Response

Status 204. No content.

Get Single Case Execution

Retrieves a single case execution according to the CaseExecution interface in the engine.

Method

GET /case-execution/{id}

Parameters

Path Parameters

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

Result

A JSON object corresponding to the CaseExecution interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the case execution.
caseInstanceId String The id of the case instance this case execution belongs to.
parentId String The id of the parent of this case execution belongs to.
caseDefinitionId String The id of the case definition this case execution belongs to.
activityId String The id of the activity this case execution belongs to.
activityName String The name of the activity this case execution belongs to.
activityType String The type of the activity this case execution belongs to.
activityDescription String The description of the activity this case execution belongs to.
active Boolean A flag indicating whether the case execution is active or not.
enabled Boolean A flag indicating whether the case execution is enabled or not.
disabled Boolean A flag indicating whether the case execution is disabled or not.

Response codes

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

Example

Request

GET /case-execution/aCaseExecutionId

Response

{
  "id"               : "aCaseExecutionId",
  "caseInstanceId"   : "aCaseInstId",
  "active"           : true,
  "enabled"          : false,
  "disabled"         : false
}

Get Local Case Execution Variable

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

Method

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

Parameters

Path Parameters

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

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A JSON object with the following properties:

Name Value Description
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 1

Request

GET /case-execution/aCaseExecutionId/localVariables/aVarName

Response

{
  "value" : {"prop1" : "a", "prop2" : "b"},
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Example 2

Request

GET /case-execution/aCaseExecutionId/localVariables/aVarName?deserializeValue=false

Response

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Get Local Case Execution Variables

Retrieves all variables of a given case execution.

Method

GET /case-execution/{id}/localVariables

Parameters

Path Parameters

Name Description
id The id of the case execution to retrieve the variables from.

Query Parameters

Name Description
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

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 The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

Response codes

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

Example 1

Request

GET /case-execution/aCaseExecutionId/localVariables

Response

{
  "aVariableKey": {
    "value" : {"prop1" : "a", "prop2" : "b"},
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
}

Example 2

Request

GET /case-execution/aCaseExecutionId/localVariables?deserializeValues=false

Response

{
  "aVariableKey": {
    "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
} 

Get Case Executions

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

Method

GET /case-execution

Parameters

Query Parameters

Name Description
caseExecutionId Filter by a case execution id.
caseInstanceId Filter by a case instance id.
businessKey Filter by the business key of the case instances the case executions belong to.
caseDefinitionId Filter by the case definition the case executions run on.
caseDefinitionKey Filter by the key of the case definition the case executions run on.
activityId Filter by the id of the activity the case execution currently executes.
active Only include active case executions. Values may be true or false.
enabled Only include enabled case executions. Values may be true or false.
disabled Only include disabled case executions. Values may be true or false.
variables Only include case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
caseInstanceVariables Only include case executions that belong to a case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are caseExecutionId, caseDefinitionKey and caseDefinitionId. 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 case execution objects. Each case execution object has the following properties:

Name Value Description
id String The id of the case execution.
caseInstanceId String The id of the case instance this case execution belongs to.
parentId String The id of the parent of this case execution belongs to.
caseDefinitionId String The id of the case definition this case execution belongs to.
activityId String The id of the activity this case execution belongs to.
activityName String The name of the activity this case execution belongs to.
activityType String The type of the activity this case execution belongs to.
activityDescription String The description of the activity this case execution belongs to.
active Boolean A flag indicating whether the case execution is active or not.
enabled Boolean A flag indicating whether the case execution is enabled or not.
disabled Boolean A flag indicating whether the case execution is disabled or not.

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 /case-execution?variables=myVariable_eq_camunda,mySecondVariable_neq_aBadValue

Response

[
  {
    "links"            : [],
    "id"               : "aCaseExecutionId",
    "caseInstanceId"   : "aCaseInstId",
    "active"           : true,
    "enabled"          : false,
    "disabled"         : false
  }
]

Get Case Executions Count

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

Method

GET /case-execution/count

Parameters

Query Parameters

Name Description
caseExecutionId Filter by a case execution id.
caseInstanceId Filter by a case instance id.
businessKey Filter by the business key of the case instances the case executions belong to.
caseDefinitionId Filter by the case definition the case executions run on.
caseDefinitionKey Filter by the key of the case definition the case executions run on.
activityId Filter by the id of the activity the case execution currently executes.
active Only include active case executions. Values may be true or false.
enabled Only include enabled case executions. Values may be true or false.
disabled Only include disabled case executions. Values may be true or false.
variables Only include case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
caseInstanceVariables Only include case executions that belong to a case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 case 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 an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /case-execution/count?variables=myVariable_eq_camunda

Response

{
  "count": 1
}

Get Single Case Execution Variable

Retrieves a variable of a given case execution.

Method

GET /case-execution/{id}/variables/{varId}

Parameters

Path Parameters

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

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A JSON object with the following properties:

Name Value Description
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 1

Request

GET /case-execution/aCaseExecutionId/variables/aVarName

Response

{
  "value" : {"prop1" : "a", "prop2" : "b"},
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Example 2

Request

GET /case-execution/aCaseExecutionId/variables/aVarName?deserializeValue=false

Response

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Get Case Execution Variables

Retrieves all variables of a given case execution.

Method

GET /case-execution/{id}/variables

Parameters

Path Parameters

Name Description
id The id of the case execution to retrieve the variables from.

Query Parameters

Name Description
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

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 The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

Response codes

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

Example

Request

GET /case-execution/aCaseExecutionId/variables

Response

{
  "aVariableKey": {
    "value" : {"prop1" : "a", "prop2" : "b"},
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
}

Example 2

Request

GET /case-execution/aCaseExecutionId/variables?deserializeValues=false

Response

{
  "aVariableKey": {
    "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
} 

Complete Case Execution

Performs a transition from ACTIVE state to COMPLETED state. In relation to the state transition it is possible to update or delete case instance variables (please note: deletion precedes update).

Method

POST /case-execution/{id}/complete

Parameters

Path Parameters

Name Description
id The id of the case execution 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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
local Indicates whether the variable must be created and/or update locally or not. If set to true, the creation or update happens locally and will not be propagated upwards in the execution hierarchy.
deletions An array containg JSON objects. Each JSON object has a property name, which is the name of the variable to delete, and a property local, to indicate whether the variable must be deleted locally or not. If local is set to true, the deletion does not propagate upwards in the case execution hierarchy.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The state transition is not allowed to be performed, for example when the case execution is enabled or is already completed. See the Introduction for the error response format.
403 application/json The case execution cannot be completed because of CMMN restrictions. See the Introduction for the error response format.
404 application/json The case execution with given id is not found. See the Introduction for the error response format.

Example

Request

POST /case-execution/aCaseExecutionId/complete

Request body:

{
  "variables":
    {
      "aVariable" : { "value" : "aStringValue", "type": "String" },
      "anotherVariable" : { "value" : true, "type": "Boolean", "local" : true }
    },
  "deletions":
     [
        { "name" : "aVariableToDelete", "local" : true },
        { "name" : "anotherVariableToDelete", "local" : false }
      ]
}

Response

Status 204. No content.

Disable Case Execution

Performs a transition from ENABLED state to DISABLED state. In relation to the state transition it is possible to update or delete case instance variables (please note: deletion precedes update).

Method

POST /case-execution/{id}/disable

Parameters

Path Parameters

Name Description
id The id of the case execution to disable.

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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
local Indicates whether the variable must be created and/or update locally or not. If set to true, the creation or update happens locally and will not be propagated upwards in the execution hierarchy.
deletions An array containg JSON objects. Each JSON object has a property name, which is the name of the variable to delete, and a property local, to indicate whether the variable must be deleted locally or not. If local is set to true the deletion does not propagate upwards in the case execution hierarchy.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The state transition is not allowed to be performed, for example when the case execution is active or is already disabled. See the Introduction for the error response format.
403 application/json The case execution cannot be disabled because of CMMN restrictions. See the Introduction for the error response format.
404 application/json The case execution with given id is not found. See the Introduction for the error response format.

Example

Request

POST /case-execution/aCaseExecutionId/disable

Request body:

{
  "variables":
    {
      "aVariable" : { "value" : "aStringValue", "type": "String" },
      "anotherVariable" : { "value" : true, "type": "Boolean", "local" : true }
    },
  "deletions":
     [
        { "name" : "aVariableToDelete", "local" : true },
        { "name" : "anotherVariableToDelete", "local" : false }
      ]
}

Response

Status 204. No content.

Update/Delete Local Case Execution Variables

Updates or deletes the variables in the context of a case execution. The updates do not propagate upwards in the case execution hierarchy. Please note: deletion precedes update.

Method

POST /case-execution/{id}/localVariables

Parameters

Path Parameters

Name Description
id The id of the case 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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
deletions An array of String keys of variables to be deleted.

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 if 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 deletion could not be executed, for example because the case execution does not exist.

Example

Request

POST /case-execution/aCaseExecutionId/localVariables

Request body:

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

Response

Status 204. No content.

Start Case Execution Manually

Performs a transition from ENABLED state to ACTIVE state. In relation to the state transition it is possible to update or delete case instance variables (please note: deletion precedes update).

Method

POST /case-execution/{id}/manual-start

Parameters

Path Parameters

Name Description
id The id of the case execution to start manually.

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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
local Indicates whether the variable must be created and/or update locally or not. If set to true, the creation or update happens locally and will not be propagated upwards in the execution hierarchy.
deletions An array containg JSON objects. Each JSON object has a property name, which is the name of the variable to delete, and a property local, to indicate whether the variable must be deleted locally or not. If local is set to true the deletion does not propagate upwards in the case execution hierarchy.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The state transition is not allowed to be performed, for example when the case execution is disabled or is already active. See the Introduction for the error response format.
403 application/json The case execution cannot be started because of CMMN restrictions. See the Introduction for the error response format.
404 application/json The case execution with given id is not found. See the Introduction for the error response format.

Example

Request

POST /case-execution/aCaseExecutionId/manual-start

Request body:

{
  "variables":
    {
      "aVariable" : { "value" : "aStringValue", "type": "String" },
      "anotherVariable" : { "value" : true, "type": "Boolean", "local" : true }
    },
  "deletions":
     [
        { "name" : "aVariableToDelete", "local" : true },
        { "name" : "anotherVariableToDelete", "local" : false }
      ]
}

Response

Status 204. No content.

Get Case Executions (POST)

Query for case executions that fulfill given parameters through a JSON object. This method is slightly more powerful than the GET query because it allows filtering by multiple case variables of types String, Number or Boolean.

Method

POST /case-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
caseExecutionId Filter by a case execution id.
caseInstanceId Filter by a case instance id.
businessKey Filter by the business key of the case instances the case executions belong to.
caseDefinitionId Filter by the case definition the case executions run on.
caseDefinitionKey Filter by the key of the case definition the case executions run on.
activityId Filter by the id of the activity the case execution currently executes.
active Only include active case executions. Values may be true or false.
enabled Only include enabled case executions. Values may be true or false.
disabled Only include disabled case executions. Values may be true or false.
variables A JSON array to only include case 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
caseInstanceVariables A JSON array to only include case executions that belong to a case instance with 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
sortBy Sort the results lexicographically by a given criterion. Valid values are caseExecutionId, caseDefinitionKey and caseDefinitionId. 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 case execution objects. Each case execution object has the following properties:

Name Value Description
id String The id of the case execution.
caseInstanceId String The id of the case instance this case execution belongs to.
parentId String The id of the parent of this case execution belongs to.
caseDefinitionId String The id of the case definition this case execution belongs to.
activityId String The id of the activity this case execution belongs to.
activityName String The name of the activity this case execution belongs to.
activityType String The type of the activity this case execution belongs to.
activityDescription String The description of the activity this case execution belongs to.
active Boolean A flag indicating whether the case execution is active or not.
enabled Boolean A flag indicating whether the case execution is enabled or not.
disabled Boolean A flag indicating whether the case execution is disabled or not.

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 /case-execution

Request body:

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

Response

[
  {
    "links" : [],
    "id"               : "aCaseExecutionId",
    "caseInstanceId"   : "aCaseInstId",
    "active"           : true,
    "enabled"          : true,
    "disabled"          : true
  }
]

Get Case Executions Count (POST)

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

Method

POST /case-instance/count

Parameters

Request Body

A JSON object with the following properties:

Name Description
caseExecutionId Filter by a case execution id.
caseInstanceId Filter by a case instance id.
businessKey Filter by the business key of the case instances the case executions belong to.
caseDefinitionId Filter by the case definition the case executions run on.
caseDefinitionKey Filter by the key of the case definition the case executions run on.
activityId Filter by the id of the activity the case execution currently executes.
active Only include active case executions. Values may be true or false.
enabled Only include enabled case executions. Values may be true or false.
variables A JSON array to only include case 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
caseInstanceVariables A JSON array to only include case executions that belong to a case instance with 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.

Result

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

Name Value Description
count Number The number of matching case 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 an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /case-execution/count

Request body:

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

Response

{
  "count" : 1
}

Re-enable Case Execution

Performs a transition from DISABLED state to ENABLED state. In relation to the state transition it is possible to update or delete case instance variables (please note: deletion precedes update).

Method

POST /case-execution/{id}/reenable

Parameters

Path Parameters

Name Description
id The id of the case execution to re-enable.

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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
local Indicates whether the variable must be created and/or update locally or not. If set to true, the creation or update happens locally and will not be propagated upwards in the execution hierarchy.
deletions An array containg JSON objects. Each JSON object has a property name, which is the name of the variable to delete, and a property local, to indicate whether the variable must be deleted locally or not. If local is set to true the deletion does not propagate upwards in the case execution hierarchy.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The state transition is not allowed to be performed, for example when the case execution is active or is already enabled. See the Introduction for the error response format.
403 application/json The case execution cannot be reenabled because of CMMN restrictions. See the Introduction for the error response format.
404 application/json The case execution with given id is not found. See the Introduction for the error response format.

Example

Request

POST /case-execution/aCaseExecutionId/reenable

Request body:

{
  "variables":
    {
      "aVariable" : { "value" : "aStringValue", "type": "String" },
      "anotherVariable" : { "value" : true, "type": "Boolean", "local" : true }
    },
  "deletions":
     [
        { "name" : "aVariableToDelete", "local" : true },
        { "name" : "anotherVariableToDelete", "local" : false }
      ]
}

Response

Status 204. No content.

Post Single Case Execution Variable (Binary)

Sets the serialized value for a binary variable.

Method

POST /case-execution/{id}/variables/{varId}/data

Parameters

Path Parameters

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

Request Body

A multipart form submit with the following parts:

Form Part Name Content Type Description
data application/octet-stream The binary data to be set.
data application/json

Deprecated: This only works if the REST API is aware of the involved Java classes.

A JSON representation of a serialized Java Object. Form part type (see below) must be provided.

type text/plain

Deprecated: This only works if the REST API is aware of the involved Java classes.

The canonical java type name of the case variable to be set. Example: foo.bar.Customer. If this part is provided, data must be a JSON object which can be converted into an instance of the provided class. The content type of the data part must be application/json in that case (see above).

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

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

POST /case-execution/aCaseExecutionId/variables/aVarName/data

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

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

(2) Post the JSON serialization of a Java Class (deprecated):

POST /case-execution/aCaseExecutionId/variables/aVarName/data

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

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

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

Update/Delete Case Execution Variables

Updates or deletes the variables of a case execution. Please note: deletion precedes update.

Method

POST /case-execution/{id}/variables

Parameters

Path Parameters

Name Description
id The id of the case 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 with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
deletions An array of String keys of variables to be deleted.

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 if 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 deletion could not be executed, for example because the case execution does not exist.

Example

Request

POST /case-execution/aCaseExecutionId/variables

Request body:

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

Response

Status 204. No content.

Put Local Case Execution Variable

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

Method

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

Parameters

Path Parameters

Name Description
id The id of the case 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 variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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 1

Request

PUT /case-execution/aCaseExecutionId/localVariables/aVarName

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

Response

Status 204. No content.

Example 2

Request

PUT /case-execution/aCaseExecutionId/localVariables/aVarName

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Response

Status 204. No content.

Post Local Case Execution Variable (Binary)

Sets the serialized value for a binary variable.

Method

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

Parameters

Path Parameters

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

Request Body

A multipart form submit with the following parts:

Form Part Name Content Type Description
data application/octet-stream The binary data to be set.
data application/json

Deprecated: This only works if the REST API is aware of the involved Java classes.

A JSON representation of a serialized Java Object. Form part type (see below) must be provided.

type text/plain

Deprecated: This only works if the REST API is aware of the involved Java classes.

The canonical java type name of the variable to be set. Example: foo.bar.Customer. If this part is provided, data must be a JSON object which can be converted into an instance of the provided class. The content type of the data part must be application/json in that case (see above).

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

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

POST /case-execution/aCaseExecutionId/localVariables/aVarName/data

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

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

(2) Post the JSON serialization of a Java Class (deprecated):

POST /case-execution/aCaseExecutionId/localVariables/aVarName/data

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

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

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

Put Single Case Execution Variable

Sets a variable of a given case execution.

Method

PUT /case-execution/{id}/variables/{varId}

Parameters

Path Parameters

Name Description
id The id of the case 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 variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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 1

Request

PUT /case-execution/aCaseExecutionId/variables/aVarName

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

Response

Status 204. No content.

Example 2

Request

PUT /case-execution/aCaseExecutionId/variables/aVarName

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Response

Status 204. No content.

Delete Single Case Instance Variable

Deletes a variable of a given case instance.

Method

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

Parameters

Path Parameters

Name Description
id The id of the case 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 /case-instance/aCaseInstanceId/variables/aVarName

Response

Status 204. No content.

Get Single Case Instance

Retrieves a single case instance according to the CaseInstance interface in the engine.

Method

GET /case-instance/{id}

Parameters

Path Parameters

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

Result

A JSON object corresponding to the CaseInstance interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the case instance.
caseDefinitionId String The id of the case definition this instance belongs to.
businessKey String The business key of the case instance.
active Boolean A flag indicating whether the case instance is active or not.
completed Boolean A flag indicating whether the case instance is completed or not.

Response codes

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

Example

Request

GET /case-instance/aCaseInstanceId

Response

{
  "id"               : "aCaseInstanceId",
  "caseDefinitionId" : "aCaseDefId",
  "businessKey"      : "aKey",
  "active"           : true,
  "completed"        : false
}

Get Case Instances

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

Method

GET /case-instance

Parameters

Query Parameters

Name Description
caseInstanceId Filter by a case instance id.
businessKey Filter by case instance business key.
caseDefinitionId Filter by the case definition the case instances run on.
caseDefinitionKey Filter by the key of the case definition the case instances run on.
active Only include active case instances. Values may be true or false.
completed Only include completed case instances. Values may be true or false.
variables Only include case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are caseInstanceId, casedefinitionKey and caseDefinitionId. 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 case instance objects. Each case instance object has the following properties:

Name Value Description
id String The id of the case instance.
caseDefinitionId String The id of the case definition that this case instance belongs to.
businessKey String The business key of the case instance.
active Boolean A flag indicating whether the case instance is active or not.
completed Boolean A flag indicating whether the case instance is completed or not.

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 /case-instance?variables=myVariable_eq_camunda,mySecondVariable_neq_aBadValue

Response

[
  {
    "links"            : [],
    "id"               : "anId",
    "caseDefinitionId" : "aCaseDefId",
    "businessKey"      : "aKey",
    "active"           : true,
    "completed"        : false
  }
]

Get Case Instances Count

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

Method

GET /case-instance/count

Parameters

Query Parameters

Name Description
caseInstanceId Filter by a case instance id.
businessKey Filter by case instance business key.
caseDefinitionId Filter by the case definition the case instances run on.
caseDefinitionKey Filter by the key of the case definition the case instances run on.
active Only include active case instances. Values may be true or false.
completed Only include completed case instances. Values may be true or false.
variables Only include case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 case 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 an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

GET /case-instance/count?variables=myVariable_eq_camunda

Response

{
  "count": 1
}

Get Single Case Instance Variable

Retrieves a variable of a given case instance.

Method

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

Parameters

Path Parameters

Name Description
id The id of the case instance to retrieve the variable from.
varId The name of the variable to get.

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A JSON object with the following properties:

Name Value Description
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 1

Request

GET /case-instance/aCaseInstanceId/variables/aVarName

Response

{
  "value" : {"prop1" : "a", "prop2" : "b"},
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Example 2

Request

GET /case-instance/aCaseInstanceId/variables/aVarName?deserializeValue=false

Response

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Get Case Instance Variables

Retrieves all variables of a given case instance.

Method

GET /case-instance/{id}/variables

Parameters

Path Parameters

Name Description
id The id of the case instance to retrieve the variables from.

Query Parameters

Name Description
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

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 The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

Response codes

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

Example 1

Request

GET /case-instance/aCaseInstanceId/variables

Response

{
  "aVariableKey": {
    "value" : {"prop1" : "a", "prop2" : "b"},
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
}

Example 2

Request

GET /case-instance/aCaseInstanceId/variables?deserializeValues=false

Response

{
  "aVariableKey": {
    "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
} 

Close Case Instance

Performs a transition from COMPLETED state to CLOSED state. In relation to the state transition it is possible to update or delete case instance variables (please note: deletion precedes update).

Method

POST /case-instance/{id}/close

Parameters

Path Parameters

Name Description
id The id of the case instance to close.

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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
local Indicates whether the variable must be created and/or update locally or not. If set to true, the creation or update happens locally and will not be propagated upwards in the execution hierarchy.
deletions An array containing JSON objects. Each JSON object has a property name, which is the name of the variable to delete.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The state transition is not allowed to be performed, for example when the case instance is active. See the Introduction for the error response format.
403 application/json The case instance cannot be closed because of CMMN restrictions. See the Introduction for the error response format.
404 application/json The case instance with given id is not found. See the Introduction for the error response format.

Example

Request

POST /case-instance/aCaseInstanceId/close

Request body:

{
  "variables":
    {
      "aVariable" : { "value" : "aStringValue", "type": "String" },
      "anotherVariable" : { "value" : true, "type": "Boolean" }
    },
  "deletions":
     [
        { "name" : "aVariableToDelete" },
        { "name" : "anotherVariableToDelete" }
      ]
}

Response

Status 204. No content.

Complete Case Instance

Performs a transition from ACTIVE state to COMPLETED state. In relation to the state transition it is possible to update or delete case instance variables (please note: deletion precedes update).

Method

POST /case-instance/{id}/complete

Parameters

Path Parameters

Name Description
id The id of the case instance 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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
local Indicates whether the variable must be created and/or update locally or not. If set to true, the creation or update happens locally and will not be propagated upwards in the execution hierarchy.
deletions An array containing JSON objects. Each JSON object has a property name, which is the name of the variable to delete.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The state transition is not allowed to be performed, for example when the case instance is already completed. See the Introduction for the error response format.
403 application/json The case instance cannot be completed because of CMMN restrictions. See the Introduction for the error response format.
404 application/json The case instance with given id is not found. See the Introduction for the error response format.

Example

Request

POST /case-instance/aCaseInstanceId/complete

Request body:

{
  "variables":
    {
      "aVariable" : { "value" : "aStringValue", "type": "String" },
      "anotherVariable" : { "value" : true, "type": "Boolean" }
    },
  "deletions":
     [
        { "name" : "aVariableToDelete" },
        { "name" : "anotherVariableToDelete" }
      ]
}

Response

Status 204. No content.

Get Case Instances (POST)

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

Method

POST /case-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
caseInstanceId Filter by a case instance id.
businessKey Filter by case instance business key.
caseDefinitionId Filter by the case definition the case instances run on.
caseDefinitionKey Filter by the key of the case definition the case instances run on.
active Only include active case instances. Values may be true or false.
completed Only include completed case instances. Values may be true or false.
variables A JSON array to only include case 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
sortBy Sort the results lexicographically by a given criterion. Valid values are caseInstanceId, caseDefinitionKey and caseDefinitionId. 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 case instance objects. Each case instance object has the following properties:

Name Value Description
id String The id of the case instance.
caseDefinitionId String The id of the case definition that this case instance belongs to.
businessKey String The business key of the case instance.
active Boolean A flag indicating whether the case instance is active or not.
completed Boolean A flag indicating whether the case instance is completed or not.

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 /case-instance

Request body:

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

Response

[
  {
    "links" : [],
    "id" : "anId",
    "caseDefinitionId" : "aCaseDefinitionId",
    "businessKey" : "aKey",
    "active" : false,
    "completed" : false
  }
]

Get Case Instances Count (POST)

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

Method

POST /case-instance/count

Parameters

Request Body

A JSON object with the following properties:

Name Description
caseInstanceId Filter by a case instance id.
businessKey Filter by case instance business key.
caseDefinitionId Filter by the case definition the case instances run on.
caseDefinitionKey Filter by the key of the case definition the case instances run on.
active Only include active case instances. Values may be true or false.
completed Only include completed case instances. Values may be true or false.
variables A JSON array to only include case 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
sortBy Sort the results lexicographically by a given criterion. Valid values are caseInstanceId, caseDefinitionKey and caseDefinitionId. 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 case 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 an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /case-instance/count

Request body:

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

Response

{
  "count" : 1
}

Post Single Case Instance Variable (Binary)

Sets the serialized value for a binary variable.

Method

POST /case-instance/{id}/variables/{varId}/data

Parameters

Path Parameters

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

Request Body

A multipart form submit with the following parts:

Form Part Name Content Type Description
data application/octet-stream The binary data to be set.
data application/json

Deprecated: This only works if the REST API is aware of the involved Java classes.

A JSON representation of a serialized Java Object. Form part type (see below) must be provided.

type text/plain

Deprecated: This only works if the REST API is aware of the involved Java classes.

The canonical java type name of the case variable to be set. Example: foo.bar.Customer. If this part is provided, data must be a JSON object which can be converted into an instance of the provided class. The content type of the data part must be application/json in that case (see above).

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

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

POST /case-instance/aCaseInstanceId/variables/aVarName/data

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

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

(2) Post the JSON serialization of a Java Class (deprecated):

POST /case-instance/aCaseInstanceId/variables/aVarName/data

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

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

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

Update/Delete Case Instance Variables

Updates or deletes the variables of a case instance. Please note: deletion precedes update.

Method

POST /case-instance/{id}/variables

Parameters

Path Parameters

Name Description
id The id of the case 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 with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
deletions An array of String keys of variables to be deleted.

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 if 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 case instance does not exist.

Example

Request

POST /case-instance/aCaseInstanceId/variables

Request body:

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

Response

Status 204. No content.

Put Single Case Instance Variable

Sets a variable of a given case instance.

Method

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

Parameters

Path Parameters

Name Description
id The id of the case 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 variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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 1

Request

PUT /case-instance/aCaseInstanceId/variables/aVarName

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

Response

Status 204. No content.

Example 2

Request

PUT /case-instance/aCaseInstanceId/variables/aVarName

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Response

Status 204. No content.

Delete Single Deployment

Deletes a deployment.

Method

DELETE /deployment/{id}

Parameters

Path Parameters

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

Query Parameters

Name Description
cascade true, if all process instances, historic process instances and jobs for this deployment should be deleted.
skipCustomListeners true, if only the built-in ExecutionListeners should be notified with the end event.

Result

This method returns no content.

Response codes

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

Example

Request

Delete a deployment with id aDeploymentId and cascade deletion to process instances, history process instances and jobs:

DELETE /deployment/aDeploymentId?cascade=true

Response

Status 204. No content.

Get Single Deployment

Retrieves a single deployment by id.

Method

GET /deployment/{id}

Parameters

Path Parameters

Name Description
id The id of the deployment.

Result

A JSON object corresponding to the Deployment interface of the engine. Its properties are as follows:

Name Value Description
id String The id of the deployment.
name String The name of the deployment.
deploymentTime Date The date time of the deployment.

Response codes

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

Example

Request

GET /deployments/someDeploymentId

Response

Status 200.

{
  "id": "someDeploymentId",
  "name": "deploymentName",
  "deploymentTime": "2013-04-23T13:42:43"
}

Get Deployments

Query for deployments that fulfill given parameters. Parameters may be the properties of deployments, such as the id or name or a range of the deployment time. The size of the result set can be retrieved by using the get deployments count method.

Method

GET /deployment

Parameters

Query Parameters

Name Description
id Filter by deployment id.
name Filter by the deployment name. Exact match.
nameLike Filter by the deployment name that the parameter is a substring of. The parameter can include the wildcard % to express like-strategy such as: starts with (%name), ends with (name%) or contains (%name%).
after Restricts to all deployments after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45
before Restricts to all deployments before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45
sortBy Sort the results lexicographically by a given criterion. Valid values are id, name and deploymentTime. 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 deployment objects. Each deployment object has the following properties:

Name Value Description
id String The id of the deployment.
name String The name of the deployment.
deploymentTime Date The date time of the deployment.

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 /deployment?name=deploymentName

Response

[
  {
    "id": "someId",
    "name": "deploymentName",
    "deploymentTime": "2013-04-23T13:42:43"
  }
]

Get Deployments Count

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

Method

GET /deployment/count

Parameters

Query Parameters

Name Description
id Filter by deployment id.
name Filter by the deployment name. Exact match.
nameLike Filter by the deployment name that the parameter is a substring of. The parameter can include the wildcard % to express like-strategy such as: starts with (%name), ends with (name%) or contains (%name%).
after Restricts to all deployments after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45
before Restricts to all deployments before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45
sortBy Sort the results lexicographically by a given criterion. Valid values are id, name and deploymentTime. 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 deployments.

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 /deployment/count?name=deploymentName

Response

{"count": 1}

Get Single Deployment Resource

Retrieves a single deployment resource by resource id for the given deployment.

Method

GET /deployment/{id}/resources/{resourceId}

Parameters

Path Parameters

Name Description
id The id of the deployment.
resourceId The id of the deployment resource.

Result

A JSON object corresponding to the Resource interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the deployment resource.
name String The name of the deployment resource.
deploymentId String The id of the deployment.

Response codes

Code Media type Description
200 application/octet-stream Request successful.
404 application/json Deployment Resource with given resource id or deployment id does not exist. See the Introduction for the error response format.

Example

Request

GET /deployments/someDeploymentId/resources/someResourceId

Response

Status 200.

{
  "id": "someResourceId",
  "name": "someResourceName",
  "deploymentId": "someDeploymentId"
}

Get Single Deployment Resource (binary)

Retrieves the binary content of a single deployment resource for the given deployment.

Method

GET /deployment/{id}/resources/{resourceId}/data

Parameters

Path Parameters

Name Description
id The id of the deployment.
resourceId The id of the deployment resource.

Result

Byte Stream.

Response codes

Code Media type Description
200 application/octet-stream Request successful.
404 application/json Deployment Resource with given resource id or deployment id does not exist. See the Introduction for the error response format.

Example

Request

GET /deployments/someDeploymentId/resources/someResourceId/data

Response

Status 200.

Byte Stream.

Get Deployment Resources

Retrieves all deployment resources of a given deployment.

Method

GET /deployment/{id}/resources

Parameters

Path Parameters

Name Description
id The id of the deployment to retrieve the deployment resources for.

Result

A JSON array containing all deployment resources of the given deployment. Each object has the following properties:

Name Value Description
id String The id of the deployment resource.
name String The name of the deployment resource.
deploymentId String The id of the deployment.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json Deployment resources for the given deployment do not exist. See the Introduction for the error response format.

Example

Request

GET /deployment/anDeploymentId/resources

Response

[
  {
    "id": "anResourceId",
    "name": "anResourceName",
    "deploymentId": "anDeploymentId"
  },
  {
    "id": "anotherResourceId",
    "name": "anotherResourceName",
    "deploymentId": "anDeploymentId"
  }
]

Post Deployment

Create a deployment.

Security Consideration

Deployments can contain custom code in form of scripts or EL expressions to customize process behavior. This may be abused for remote execution of arbitrary code. See the section on security considerations for custom code in the user guide for details.

Method

POST /deployment/create

Parameters

Request Body

A multipart form submit with the following parts:

Form Part Name Content Type Description
deployment-name text/plain The name for the deployment to be created.
enable-duplicate-filtering text/plain A flag indicating whether the process engine should perform duplicate checking for the deployment or not. This allows you to check if a deployment with the same name and the same resouces already exists and if true, not create a new deployment but instead return the existing deployment. The default value is false.
deploy-changed-only text/plain A flag indicating whether the process engine should perform duplicate checking on a per-resource basis. If set to true, only those resources that have actually changed are deployed. Checks are made against resources included previous deployments of the same name and only against the latest versions of those resources. If set to true, the option enable-duplicate-filtering is overridden and set to true.
* application/octet-stream The binary data to create the deployment resource. It is possible to have more than one form part with different form part names for the binary data to create a deployment.

Result

A JSON object corresponding to the Deployment interface in the engine. Its properties are as follows:

Name Value Description
links List Link to the newly created deployment with method, href and rel.
id String The id of the deployment.
name String The name of the deployment.
deploymentTime String The time when the deployment was created.

Response codes

Code Media type Description
200 application/json Request successful.

Example

Request

Post data for a new deployment:

POST /deployment/create

--28319d96a8c54b529aa9159ad75edef9
Content-Disposition: form-data; name="deployment-name"

aName
--28319d96a8c54b529aa9159ad75edef9
Content-Disposition: form-data; name="enable-duplicate-filtering"

true
--28319d96a8c54b529aa9159ad75edef9
Content-Disposition: form-data; name="data"; filename="test.bpmn"

<?xml version="1.0" encoding="UTF-8"?>
<bpmn2:definitions ...>
  <!-- BPMN 2.0 XML omitted -->
</bpmn2:definitions>
--28319d96a8c54b529aa9159ad75edef9--

Response

Status 200.

{
  "links": [
    {
      "method": "GET",
      "href": "http://localhost:38080/rest-test/deployment/aDeploymentId",
      "rel": "self"
    }
  ],
  "id": "aDeploymentId",
  "name": "aName",
  "deploymentTime": "2013-01-23T13:59:43"
}

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 or not.

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 from.
varId The name of the variable to get.

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A JSON object with the following properties:

Name Value Description
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 1

Request

GET /execution/anExecutionId/localVariables/aVarName

Response

{
  "value" : {"prop1" : "a", "prop2" : "b"},
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Example 2

Request

GET /execution/anExecutionId/localVariables/aVarName?deserializeValue=false

Response

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

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

Query Parameters

Name Description
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

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 The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 1

Request

GET /execution/anExecutionId/localVariables

Response

{
  "aVariableKey": {
    "value" : {"prop1" : "a", "prop2" : "b"},
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
}

Example 2

Request

GET /execution/anExecutionId/localVariables?deserializeValues=false

Response

{
  "aVariableKey": {
    "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
} 

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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to.
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 or not.

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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to.
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 deletions. 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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
deletions An array of String keys of variables to be deleted.

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 if 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
variables

A JSON object containing variable key-value pairs. Each key is a variable name and each value a JSON variable value object.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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:

{"variables" :
    {"aVariable" : {"value" : true, "type": "Boolean"},
     "anotherVariable" : {"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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to.
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 or not.

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 therefore it is 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 be true or false.
suspended Only include suspended executions. Values may be true or false.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to.
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.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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 variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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 1

Request

PUT /execution/anExecutionId/localVariables/aVarName

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

Response

Status 204. No content.

Example 2

Request

PUT /execution/anExecutionId/localVariables/aVarName

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Response

Status 204. No content.

Post Local Execution Variable (Binary)

Sets the value for a binary variable.

Method

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

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 multipart form submit with the following parts:

Form Part Name Content Type Description
data application/octet-stream The binary data to be set.
data application/json

Deprecated: This only works if the REST API is aware of the involved Java classes.

A JSON representation of a serialized Java Object. Form part type (see below) must be provided.

type text/plain

Deprecated: This only works if the REST API is aware of the involved Java classes.

The canonical java type name of the variable to be set. Example: foo.bar.Customer. If this part is provided, data must be a JSON object which can be converted into an instance of the provided class. The content type of the data part must be application/json in that case (see above).

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

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

POST /execution/anExecutionId/localVariables/aVarName/data

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

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

(2) Post the JSON serialization of a Java Class (deprecated):

POST /execution/anExecutionId/localVariables/aVarName/data

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

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

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

Get Filters

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

Method

GET /filter

Parameters

Query Parameters

Name Description
filterId Filter by the id of the filter.
resourceType Filter by the resource type of the filter, e.g., Task.
name Filter by the name of the filter.
nameLike Filter by the name that the parameter is a substring of.
owner Filter by the user id of the owner of the filter.
itemCount If set to true each filter result will contain an itemCount property with the number of items matched by the filter itself.
sortBy Sort the results lexicographically by a given criterion. Valid values are filterId, 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 filter objects. Each filter object has the following properties:

Name Value Description
id String The id of the filter.
resourceType String The resource type of the filter.
name String The name of the filter.
owner String The user id of the owner of the filter.
query Object The query of the filter as a JSON object.
properties Object The properties of a filter as a JSON object.
itemCount Long The number of items matched by the filter itself. Note: Only exists if the query parameter itemCount was set to true

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 /filter?resourceType=Task

Response

Status 200.

[
  {
    "id": "aFilter",
    "resourceType": "Task",
    "name": "My Filter",
    "owner": "jonny1",
    "query": {
      "assignee": "jonny1"
    },
    "properties": {
      "color": "#58FA58",
      "description": "Filters assigned to me"
    }
  },
  {
    "id": "anotherFilter",
    "resourceType": "Task",
    "name": "Accountants Filter",
    "owner": "demo",
    "query": {
      "candidateGroup": "accountant"
    },
    "properties": {
      "description": "Filters assigned to me",
      "priority": 10
    }
  }
]

Request with itemCount enabled

GET /filter?resourceType=Task&itemCount=true

Response with itemCount

Status 200.

[
  {
    "id": "aFilter",
    "resourceType": "Task",
    "name": "My Filter",
    "owner": "jonny1",
    "query": {
      "assignee": "jonny1"
    },
    "properties": {
      "color": "#58FA58",
      "description": "Filters assigned to me"
    },
    "itemCount": 13
  },
  {
    "id": "anotherFilter",
    "resourceType": "Task",
    "name": "Accountants Filter",
    "owner": "demo",
    "query": {
      "candidateGroup": "accountant"
    },
    "properties": {
      "description": "Filters assigned to me",
      "priority": 10
    },
    "itemCount": 42
  }
]

Get Filters Count

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

Method

GET /filter/count

Parameters

Query Parameters

Name Description
filterId Restrict to filters that have the given id.
resourceType Restrict to filters that have the given resource type, e.g., Task.
name Restrict to filters that have the given name.
nameLike Restrict to filters that have a name with the given parameter value as substring.
owner Restrict to filters that the given user owns.

Result

A JSON object with a single count property.

Name Value Description
count Number The number of filters 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 /filter/count?resourceType=Task&owner=aUserId

Response

Status 200.

{
  "count": 3
}

Get Single Filter

Retrieves a single filter according to the Filter interface in the engine.

Method

GET /filter/{id}

Parameters

Path Parameters

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

Query Parameters

Name Description
itemCount If set to true each filter result will contain an itemCount property with the number of items matched by the filter itself.

Result

A JSON object corresponding to the Filter interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the filter.
resourceType String The resource type of the filter, e.g., Task.
name String The name of the filter.
owner String The user id of the owner of the filter.
query Object The save query of the filter as JSON object.
properties Object The properties of the filter as JSON object.
itemCount Long The number of items matched by the filter itself. Note: Only exists if the query parameter itemCount was set to true

Response codes

Code Media type Description
200 application/json Request successful.
403 application/json The authenticated user is unauthorized to read this filter. See the Introduction for the error response format.
404 application/json Filter with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /filter/aFilterId

Response

Status 200.

{
  "id": "9917d731-3cde-11e4-b704-f0def1e59da8",
  "name": "Accounting Tasks",
  "owner": null,
  "properties": {
    "color": "#3e4d2f",
    "description": "Tasks assigned to group accounting",
    "priority": 5
  },
  "query": {
    "candidateGroup": "accounting"
  },
  "resourceType": "Task"
}

Request with itemCount enabled

GET /filter/aFilterId?itemCount=true

Response with itemCount

Status 200.

{
  "id": "9917d731-3cde-11e4-b704-f0def1e59da8",
  "name": "Accounting Tasks",
  "owner": null,
  "properties": {
    "color": "#3e4d2f",
    "description": "Tasks assigned to group accounting",
    "priority": 5
  },
  "query": {
    "candidateGroup": "accounting"
  },
  "resourceType": "Task",
  "itemCount": 23
}

Create Filter

Create a new filter.

Security Consideration

The query parameter of the request body takes a JSON-serialized query. Some query types (e.g. task queries) allow to specify EL expressions in their parameters and may therefore be abused for remote code execution. See the section on security considerations for custom code in the user guide for details.

Method

POST /filter/create

Parameters

Request Body

A JSON object with the following properties:

Name Type Description
resourceType String The resource type of the filter, e.g., Task
name String The name of the filter.
owner String The user id of the owner of the filter.
query Object A JSON object which corresponds to the JSON body of a REST query. I.e., a filter which has the resourceType Task must contain a query which is a valid task query (see Task).
properties Object A JSON object containing various properties of the filter. The properties are user defined and no required properties exist. Properties can be used to save the priority or the description of a filter.

Result

A JSON object corresponding to the Filter interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the filter.
resourceType String The resource type of the filter, e.g., Task.
name String The name of the filter.
owner String The user id of the owner of the filter.
query Object The save query of the filter as JSON object.
properties Object The properties of the filter as JSON object.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json Filter was invalid. See Introduction for the error response format.
403 application/json The authenticated user is unauthorized to create a new filter. See the Introduction for the error response format.

Example

Request

POST /filter/create

Request body:

{
  "resourceType": "Task",
  "name": "Accounting Tasks",
  "owner": "jonny1",
  "query": {
    "candidateGroup": "accounting"
  },
  "properties": {
    "color": "#3e4d2f",
    "description": "Tasks assigned to group accounting",
    "priority": 5
  }
}

Response

Status 200.

{
  "id": "aFilterId",
  "resourceType": "Task",
  "name": "Accounting Tasks",
  "owner": "jonny1",
  "query": {
    "candidateGroup": "accounting"
  },
  "properties": {
    "color": "#3e4d2f",
    "description": "Tasks assigned to group accounting",
    "priority": 5
  }
}

Update Filter

Update an existing filter.

Security Consideration

The query parameter of the request body takes a JSON-serialized query. Some query types (e.g. task queries) allow to specify EL expressions in their parameters and may therefore be abused for remote code execution. See the section on security considerations for custom code in the user guide for details.

Method

PUT /filter/{id}

Parameters

Request Body

A JSON object with the following properties:

Name Type Description
resourceType String The resource type of the filter, e.g., Task
name String The name of the filter.
owner String The user id of the owner of the filter.
query Object A JSON object which corresponds to the JSON body of a REST query. I.e., a filter which has the resourceType Task must contain a query which is a valid task query (see Task).
properties Object A JSON object containing various properties of the filter. The properties are user defined and no required properties exist. Properties can be used to save the priority or the description of a filter.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Filter was invalid. See Introduction for the error response format.
403 application/json The authenticated user is unauthorized to update this filter. See the Introduction for the error response format.
404 application/json Filter cannot be found. See the Introduction for the error response format.

Example

Request

PUT /filter/aFilterID

Request body:

{
  "resourceType": "Task",
  "name": "My Tasks",
  "owner": "jonny1",
  "query": {
    "assignee": "jonny1"
  },
  "properties": {
    "color": "#99CCFF",
    "description": "Tasks assigned to me",
    "priority": -10
  }
}

Response

Status 204. No content.

Delete Filter

Deletes a filter by id.

Method

DELETE /filter/{id}

Parameters

Path Parameters

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

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
403 application/json The authenticated user is unauthorized to delete this filter. See the Introduction for the error response format.
404 application/json Filter cannot be found. See the Introduction for the error response format.

Example

Request

DELETE /filter/aFilterId

Response

Status 204. No content.

Execute Filter Single Result

Executes the saved query of the filter and returns the single result.

Method

GET /filter/{id}/singleResult

Parameters

Path Parameters

Name Description
id The id of the filter to execute.

Result

A JSON object corresponding to the matching entity interface in the engine. This depends on the saved query in the filter. Therefore it is not possible to specify a generic result format, i.e., if the resource type of the filter is Task the result will correspond with the Task interface in the engine.

Response codes

Code Media type Description
200 application/json Request successful.
200 application/hal+json Request successful. In case of an expected HAL response.
204 Request successful, but the result was empty.
400 application/json The executed filter returned more than one single result. See the Introduction for the error response format.
403 application/json The authenticated user is unauthorized to read this filter. See the Introduction for the error response format.
404 application/json Filter with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /filter/aTaskFilterId/singleResult

Response

Status 200.

{
  "assignee": "jonny1",
  "caseDefinitionId": null,
  "caseExecutionId": null,
  "caseInstanceId": null,
  "created": "2014-09-15T15:45:48",
  "delegationState": null,
  "description": null,
  "due": null,
  "executionId": "aExecutionId",
  "followUp": null,
  "formKey": null,
  "id": "aTaskId",
  "name": "Task 2",
  "owner": null,
  "parentTaskId": null,
  "priority": 50,
  "processDefinitionId": "aProcessId",
  "processInstanceId": "aProcessInstanceId",
  "suspended": false,
  "taskDefinitionKey": "aTaskKey"
}

Execute Filter Single Result (POST)

Executes the saved query of the filter and returns the single result. This method is slightly more powerful then the GET query because it allows to extend the saved query of the filter.

Security Consideration

The request body of this method takes a JSON-serialized query. Some query types (e.g. task queries) allow to specify EL expressions in their parameters and may therefore be abused for remote code execution. See the section on security considerations for custom codesecurity considerations for custom code in the user guide for details.

Method

POST /filter/{id}/singleResult

Parameters

Path Parameters

Name Description
id The id of the filter to execute.

Request Body

A JSON object which corresponds to the type of the saved query of the filter, i.e., if the resource type of the filter is Task the body should form a valid task query corresponding to the Task resource.

Result

A JSON object corresponding to the corresponding entity interface in the engine. This depends on the saved query in the filter. Therefore it is not possible specify a generic result format, i.e., if the resource type of the filter is Task the result will correspond with the Task interface in the engine.

Response codes

Code Media type Description
200 application/json Request successful.
200 application/hal+json Request successful. In case of an expected HAL response.
204 Request successful, but the result was empty.
400 application/json The executed filter returned more than one single result or the extending query was invalid. See the Introduction for the error response format.
403 application/json The authenticated user is unauthorized to read this filter. See the Introduction for the error response format.
404 application/json Filter with given id does not exist. See the Introduction for the error response format.

Example

Request

POST filter/aTaskFilterId/singleResult

Request Body:

{
  "assignee": "jonny1",
  "taskDefinitionKey": "aTaskKey"
}

Response

Status 200.

{
  "assignee": "jonny1",
  "caseDefinitionId": null,
  "caseExecutionId": null,
  "caseInstanceId": null,
  "created": "2014-09-15T15:45:48",
  "delegationState": null,
  "description": null,
  "due": null,
  "executionId": "aExecutionId",
  "followUp": null,
  "formKey": null,
  "id": "aTaskId",
  "name": "Task 2",
  "owner": null,
  "parentTaskId": null,
  "priority": 50,
  "processDefinitionId": "aProcessId",
  "processInstanceId": "aProcessInstanceId",
  "suspended": false,
  "taskDefinitionKey": "aTaskKey"
}

Execute Filter List

Executes the saved query of the filter and returns the result list.

Method

GET /filter/{id}/list

Parameters

Path Parameters

Name Description
id The id of the filter to execute.

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.

Result

A JSON array containing JSON objects corresponding to the matching entity interface in the engine. This depends on the saved query in the filter. Therefore it is not possible to specify a generic result format, i.e., if the resource type of the filter is Task the result will correspond with the Task interface in the engine.

Response codes

Code Media type Description
200 application/json Request successful.
200 application/hal+json Request successful. In case of an expected HAL response.
403 application/json The authenticated user is unauthorized to read this filter. See the Introduction for the error response format.
404 application/json Filter with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /filter/aTaskFilterId/list/?firstResult=0&maxResults=2

Response

Status 200.

[
  {
    "assignee": "jonny1",
    "caseDefinitionId": null,
    "caseExecutionId": null,
    "caseInstanceId": null,
    "created": "2014-09-15T15:45:48",
    "delegationState": null,
    "description": null,
    "due": null,
    "executionId": "aExecutionId",
    "followUp": null,
    "formKey": null,
    "id": "aTaskId",
    "name": "Task 2",
    "owner": null,
    "parentTaskId": null,
    "priority": 50,
    "processDefinitionId": "aProcessId",
    "processInstanceId": "aProcessInstanceId",
    "suspended": false,
    "taskDefinitionKey": "aTaskKey"
  },
  {
    "assignee": "demo",
    "caseDefinitionId": null,
    "caseExecutionId": null,
    "caseInstanceId": null,
    "created": "2014-09-15T10:42:18",
    "delegationState": null,
    "description": null,
    "due": null,
    "executionId": "anotherExecutionId",
    "followUp": null,
    "formKey": null,
    "id": "anotherTaskId",
    "name": "Task 2",
    "owner": null,
    "parentTaskId": null,
    "priority": 50,
    "processDefinitionId": "anotherProcessId",
    "processInstanceId": "anotherProcessInstanceId",
    "suspended": false,
    "taskDefinitionKey": "anotherTaskKey"
  }
]

Execute Filter List (POST)

Executes the saved query of the filter and returns the result list. This method is slightly more powerful then the GET query because it allows to extend the saved query of the filter.

Security Consideration

The request body of this method takes a JSON-serialized query. Some query types (e.g. task queries) allow to specify EL expressions in their parameters and may therefore be abused for remote code execution. See the section on security considerations for custom codesecurity considerations for custom code in the user guide for details.

Method

POST /filter/{id}/list

Parameters

Path Parameters

Name Description
id The id of the filter to execute.

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 which corresponds to the type of the saved query of the filter, i.e., if the resource type of the filter is Task the body should form a valid task query corresponding to the Task resource.

Result

A JSON array containing JSON objects corresponding to the matching entity interface in the engine. This depends on the saved query in the filter. Therefore it is not possible to specify a generic result format, i.e., if the resource type of the filter is Task the result will correspond with the Task interface in the engine.

Response codes

Code Media type Description
200 application/json Request successful.
200 application/hal+json Request successful. In case of an expected HAL response.
400 application/json The extending query was invalid. See the Introduction for the error response format.
403 application/json The authenticated user is unauthorized to read this filter. See the Introduction for the error response format.
404 application/json Filter with given id does not exist. See the Introduction for the error response format.

Example

Request

POST /filter/aTaskFilterId/list/?firstResult=0&maxResults=2

Request Body:

{
  "assignee": "jonny1",
  "taskDefinitionKey": "aTaskKey"
}

Response

Status 200.

[
  {
    "assignee": "jonny1",
    "caseDefinitionId": null,
    "caseExecutionId": null,
    "caseInstanceId": null,
    "created": "2014-09-15T15:45:48",
    "delegationState": null,
    "description": null,
    "due": null,
    "executionId": "aExecutionId",
    "followUp": null,
    "formKey": null,
    "id": "aTaskId",
    "name": "Task 2",
    "owner": null,
    "parentTaskId": null,
    "priority": 50,
    "processDefinitionId": "aProcessId",
    "processInstanceId": "aProcessInstanceId",
    "suspended": false,
    "taskDefinitionKey": "aTaskKey"
  }
]

Execute Filter Count

Executes the saved query of the filter and returns the count.

Method

GET /filter/{id}/count

Parameters

Path Parameters

Name Description
id The id of the filter to execute.

Result

A JSON object with a single count property.

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

Response codes

Code Media type Description
200 application/json Request successful.
403 application/json The authenticated user is unauthorized to read this filter. See the Introduction for the error response format.
404 application/json Filter with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /filter/aTaskFilterId/count

Response

Status 200.

{
  "count": 2
}

Execute Filter Count (POST)

Executes the saved query of the filter and returns the count. This method is slightly more powerful then the GET query because it allows to extend the saved query of the filter.

Security Consideration

The request body of this method takes a JSON-serialized query. Some query types (e.g. task queries) allow to specify EL expressions in their parameters and may therefore be abused for remote code execution. See the section on security considerations for custom codesecurity considerations for custom code in the user guide for details.

Method

POST /filter/{id}/count

Parameters

Path Parameters

Name Description
id The id of the filter to execute.

Request Body

A JSON object which corresponds to the type of the saved query of the filter, i.e., if the resource type of the filter is Task the body should form a valid task query corresponding to the Task resource.

Result

A JSON object with a single count property.

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

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json The extending query was invalid. See the Introduction for the error response format.
403 application/json The authenticated user is unauthorized to read this filter. See the Introduction for the error response format.
404 application/json Filter with given id does not exist. See the Introduction for the error response format.

Example

Request

POST filter/aTaskFilterId/singleResult

Request Body:

{
  "assignee": "jonny1",
  "taskDefinitionKey": "aTaskKey"
}

Response

Status 200.

{
  "count": 1
}

Filter Resource Options

The /filter resource supports two custom OPTIONS requests, one for the resource as such and one for individual filter instances. The OPTIONS request allows you to check for the set of available operations that the currently authenticated user can perform on the /filter resource. Whether the user can perform an operation or not may depend on various factors, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Method

OPTIONS /filter for available interactions on resource

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

Result

A JSON object with a single property named links, providing a list of resource links that are allowed actions for the current user. 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 (ie. 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 /filter/aFilterId

Response

Status 200.

{"links":[
  {"method": "GET", href":"http://localhost:8080/engine-rest/filter/aFilterId", "rel":"self"},
  {"method": "GET", href":"http://localhost:8080/engine-rest/filter/aFilterId/singleResult", "rel":"singleResult"}
  {"method": "POST", href":"http://localhost:8080/engine-rest/filter/aFilterId/singleResult", "rel":"singleResult"}
  {"method": "GET", href":"http://localhost:8080/engine-rest/filter/aFilterId/list", "rel":"list"}
  {"method": "POST", href":"http://localhost:8080/engine-rest/filter/aFilterId/list", "rel":"list"}
  {"method": "GET", href":"http://localhost:8080/engine-rest/filter/aFilterId/count", "rel":"count"}
  {"method": "POST", href":"http://localhost:8080/engine-rest/filter/aFilterId/count", "rel":"count"}
  {"method": "PUT", href":"http://localhost:8080/engine-rest/filter/aFilterId", "rel":"update"},
  {"method": "DELETE", href":"http://localhost:8080/engine-rest/filter/aFilterId", "rel":"delete"}]}

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.

Result

This method returns no content.

Response codes

Code Media type Description
200 application/json Request successful.
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
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 member 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

Result

This method returns no content.

Response codes

Code Media type Description
200 application/json Request successful.
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
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

Path Parameters

Name Description
id The id of the group
userId The id of user to add to the group

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
500 application/json In case an internal error occurs. See the Introduction for the error response format.

Example

Request

PUT /group/sales/members/jonny1

Response

Status 204. No content.

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 or not may depend on various things, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Method

OPTIONS /group for available interactions on resource

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

Parameters

Path Parameters

Name Description
id The id of the group

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 (ie. 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

This method takes no 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.
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
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

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
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

Status 204. No content.

Get Single Activity Instance (Historic)

Retrieves a single historic activity instance according to the HistoricActivityInstance interface in the engine.

Method

GET /history/activity-instance/{id}

Parameters

Path Parameters

Name Description
id The id of the historic activity instance to be retrieved.

Result

A JSON object corresponding to the HistoricActivityInstance interface in the engine. Its properties are as follows:

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).
canceled Boolean If true, this activity instance is canceled.
completeScope Boolean If true, this activity instance did complete a BPMN 2.0 scope

Response codes

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

Example

Request

GET /history/activity-instance/aActivityInstId

Response

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

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.
canceled Only include canceled activity instances. Values may be true or false.
completeScope Only include activity instances which completed a scope. Values may be true or false.
startedBefore Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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).
canceled Boolean If true, this activity instance is canceled.
completeScope Boolean If true, this activity instance did complete a BPMN 2.0 scope

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

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

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.
canceled Only include canceled activity instances. Values may be true or false.
completeScope Only include activity instances which completed a scope. Values may be true or false.
startedBefore Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.

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 Single Case Activity Instance (Historic)

Retrieves a single historic case activity instance according to the HistoricCaseActivityInstance interface in the engine.

Method

GET /history/case-activity-instance/{id}

Parameters

Path Parameters

Name Description
id The id of the historic case activity instance to be retrieved.

Result

A JSON object corresponding to the HistoricCaseActivityInstance interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the case activity instance.
parentCaseActivityInstanceId String The id of the parent case activity instance.
caseActivityId String The id of the case activity that this object is an instance of.
caseActivityName String The name of the case activity that this object is an instance of.
caseActivityType String The type of the activity this case execution belongs to.
caseDefinitionId String The id of the case definition that this case activity instance belongs to.
caseInstanceId String The id of the case instance that this case activity instance belongs to.
caseExecutionId String The id of the case execution that executed this case activity instance.
taskId String The id of the task that is associated to this case activity instance. Is only set if the case activity is a human task.
calledProcessInstanceId String The id of the called process instance. Is only set if the case activity is a process task.
calledCaseInstanceId String The id of the called case instance. Is only set if the case activity is a case task.
createTime String The time the instance was created. 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).
available Boolean If true, this case activity instance is available.
enabled Boolean If true, this case activity instance is enabled.
disabled Boolean If true, this case activity instance is disabled.
active Boolean If true, this case activity instance is active.
failed Boolean If true, this case activity instance is failed.
suspended Boolean If true, this case activity instance is suspended.
completed Boolean If true, this case activity instance is completed.
terminated Boolean If true, this case activity instance is terminated.

Response codes

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

Example

Request

GET /history/case-activity-instance/aCaseActivityInstId

Response

{
  "active": false,
  "available": true,
  "calledCaseInstanceId": "aHistoricCalledCaseInstanceId",
  "calledProcessInstanceId": "aHistoricCalledProcessInstanceId",
  "caseActivityId": "aCaseActivity",
  "caseActivityName": "aCaseActivityName",
  "caseDefinitionId": "aCaseDefId",
  "caseExecutionId": "aCaseExecutionId",
  "caseInstanceId": "aCaseInstId",
  "completed": false,
  "createTime": "2013-04-23T11:20:43",
  "disabled": false,
  "durationInMillis": 2000,
  "enabled": false,
  "endTime": "2013-04-23T18:42:43",
  "failed": false,
  "id": "aCaseActivityInstId",
  "parentCaseActivityInstanceId": "aHistoricParentCaseActivityInstanceId",
  "suspended": false,
  "taskId": "aTaskId",
  "terminated": false
}

Get Case Activity Instances (Historic)

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

Method

GET /history/case-activity-instance

Parameters

Query Parameters

Name Description
caseActivityInstanceId Filter by case activity instance id.
caseInstanceId Filter by case instance id.
caseDefinitionId Filter by case definition id.
caseExecutionId Filter by the id of the case execution that executed the case activity instance.
caseActivityId Filter by the case activity id (according to CMMN 1.0 XML).
caseActivityName Filter by the case activity name (according to CMMN 1.0 XML).
caseActivityType Filter by the case activity type (according to CMMN 1.0 XML).
createdBefore Restrict to instances that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfter Restrict to instances that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
endedBefore Restrict to instances that ended before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
endedAfter Restrict to instances that ended after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finished Only include finished case activity instances. Values may be true or false.
unfinished Only include unfinished case activity instances. Values may be true or false.
available Only include available case activity instances. Values may be true or false.
enabled Only include enabled case activity instances. Values may be true or false.
disabled Only include disabled case activity instances. Values may be true or false.
active Only include active case activity instances. Values may be true or false.
completed Only include completed case activity instances. Values may be true or false.
terminated Only include terminated case activity instances. Values may be true or false.
sortBy Sort the results by a given criterion. Valid values are caseActivityInstanceID, caseInstanceId, caseExecutionId, caseActivityId, caseActivityName, createTime, endTime, duration, caseDefinitionId. 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 case activity instance objects. Each historic activity instance object has the following properties:

Name Value Description
id String The id of the case activity instance.
parentCaseActivityInstanceId String The id of the parent case activity instance.
caseActivityId String The id of the case activity that this object is an instance of.
caseActivityName String The name of the case activity that this object is an instance of.
caseActivityType String The type of the activity this case execution belongs to.
caseDefinitionId String The id of the case definition that this case activity instance belongs to.
caseInstanceId String The id of the case instance that this case activity instance belongs to.
caseExecutionId String The id of the case execution that executed this case activity instance.
taskId String The id of the task that is associated to this case activity instance. Is only set if the case activity is a human task.
calledProcessInstanceId String The id of the called process instance. Is only set if the case activity is a process task.
calledCaseInstanceId String The id of the called case instance. Is only set if the case activity is a case task.
createTime String The time the instance was created. 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).
available Boolean If true, this case activity instance is available.
enabled Boolean If true, this case activity instance is enabled.
disabled Boolean If true, this case activity instance is disabled.
active Boolean If true, this case activity instance is active.
completed Boolean If true, this case activity instance is completed.
terminated Boolean If true, this case activity instance is terminated.

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/case-activity-instance?caseActivityName=aCaseActivityName&completed=false

Response

[
  {
    "active": false,
    "available": true,
    "calledCaseInstanceId": "aHistoricCalledCaseInstanceId",
    "calledProcessInstanceId": "aHistoricCalledProcessInstanceId",
    "caseActivityId": "aCaseActivity",
    "caseActivityName": "aCaseActivityName",
    "caseDefinitionId": "aCaseDefId",
    "caseExecutionId": "aCaseExecutionId",
    "caseInstanceId": "aCaseInstId",
    "completed": false,
    "createTime": "2013-04-23T11:20:43",
    "disabled": false,
    "durationInMillis": 2000,
    "enabled": false,
    "endTime": "2013-04-23T18:42:43",
    "id": "aCaseActivityInstId",
    "parentCaseActivityInstanceId": "aHistoricParentCaseActivityInstanceId",
    "taskId": "aTaskId",
    "terminated": false
  }
]

Get Case Activity Instances Count

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

Method

GET /history/case-activity-instance/count

Parameters

Query Parameters

Name Description
caseActivityInstanceId Filter by case activity instance id.
caseInstanceId Filter by case instance id.
caseDefinitionId Filter by case definition id.
caseExecutionId Filter by the id of the case execution that executed the case activity instance.
caseActivityId Filter by the case activity id (according to CMMN 1.0 XML).
caseActivityName Filter by the case activity name (according to CMMN 1.0 XML).
caseActivityType Filter by the case activity type (according to CMMN 1.0 XML).
createdBefore Restrict to instances that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfter Restrict to instances that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
endedBefore Restrict to instances that ended before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
endedAfter Restrict to instances that ended after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finished Only include finished case activity instances. Values may be true or false.
unfinished Only include unfinished case activity instances. Values may be true or false.
available Only include available case activity instances. Values may be true or false.
enabled Only include enabled case activity instances. Values may be true or false.
disabled Only include disabled case activity instances. Values may be true or false.
active Only include active case activity instances. Values may be true or false.
completed Only include completed case activity instances. Values may be true or false.
terminated Only include terminated case 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/case-activity-instance?caseActivityName=aCaseActivityName&completed=false

Response

{
  "count": 1
}

Get Single Case Instance

Retrieves a single historic case instance according to the HistoricCaseInstance interface in the engine.

Method

GET /history/case-instance/{id}

Parameters

Path Parameters

Name Description
id The id of the historic case instance to be retrieved.

Result

A JSON object corresponding to the HistoricCaseInstance interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the case instance.
businessKey String The business key of the case instance.
caseDefinitionId String The id of the case definition that this case instance belongs to.
createTime String The time the instance was created. Has the format yyyy-MM-dd'T'HH:mm:ss.
closeTime String The time the instance was closed. Has the format yyyy-MM-dd'T'HH:mm:ss.
durationInMillis Number The time the instance took to finish (in milliseconds).
createUserId String The id of the user who created the case instance.
superCaseInstanceId String The id of the parent case instance, if it exists.
active Boolean If true, this case instance is active.
completed Boolean If true, this case instance is completed.
terminated Boolean If true, this case instance is terminated.
failed Boolean If true, this case instance is failed.
suspended Boolean If true, this case instance is suspended.
closed Boolean If true, this case instance is closed.

Response codes

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

Example

Request

GET /history/case-instance/aCaseInstId

Response

{
  "id": "aCaseInstId",
  "businessKey": "aKey",
  "caseDefinitionId": "aCaseDefId",
  "createTime": "2013-03-23T13:42:43",
  "closeTime": "2013-03-23T13:42:45",
  "durationInMillis": 2000,
  "createUserId": "aStartUserId",
  "superCaseInstanceId": "aSuperCaseInstanceId",
  "active": true,
  "completed": false,
  "terminated": false,
  "failed": false,
  "suspended": false,
  "closed": false
}

Get Case Instances

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

Method

GET /history/case-instance

Parameters

Query Parameters

Name Description
caseInstanceId Filter by case instance id.
caseInstanceIds Filter by case instance ids. Must be a comma-separated list of case instance ids.
caseDefinitionId Filter by the case definition the instances run on.
caseDefinitionKey Filter by the key of the case definition the instances run on.
caseDefinitionKeyNotIn Exclude instances that belong to a set of case definitions. Must be a comma-separated list of case definition keys.
caseDefinitionName Filter by the name of the case definition the instances run on.
caseDefinitionNameLike Filter by case definition names that the parameter is a substring of.
caseInstanceBusinessKey Filter by case instance business key.
caseInstanceBusinessKeyLike Filter by case instance business key that the parameter is a substring of.
createdBefore Restrict to instances that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfter Restrict to instances that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
closedBefore Restrict to instances that were closed before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
closedAfter Restrict to instances that were closed after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdBy Only include case instances that were created by the given user.
superCaseInstanceId Restrict query to all case instances that are sub case instances of the given case instance. Takes a case instance id.
subCaseInstanceId Restrict query to one case instance that has a sub case instance with the given id.
active Only include active case instances. Values may be true or false.
completed Only include completed case instances. Values may be true or false.
terminated Only include terminated case instances. Values may be true or false.
closed Only include closed case instances. Values may be true or false.
notClosed Only include not closed case instances. Values may be true or false.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, createTime, closeTime, 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 case instance objects. Each historic case instance object has the following properties:

Name Value Description
id String The id of the case instance.
businessKey String The business key of the case instance.
caseDefinitionId String The id of the case definition that this case instance belongs to.
createTime String The time the instance was created. Has the format yyyy-MM-dd'T'HH:mm:ss.
closeTime String The time the instance was closed. Has the format yyyy-MM-dd'T'HH:mm:ss.
durationInMillis Number The time the instance took to finish (in milliseconds).
createUserId String The id of the user who created the case instance.
superCaseInstanceId String The id of the parent case instance, if it exists.
active Boolean If true, this case instance is active.
completed Boolean If true, this case instance is completed.
terminated Boolean If true, this case instance is terminated.
closed Boolean If true, this case instance is closed.

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/case-instance?closedAfter=2013-01-01T00:00:00&closedBefore=2013-04-01T23:59:59

Response

[
  {
    "id": "aCaseInstId",
    "businessKey": "aKey",
    "caseDefinitionId": "aCaseDefId",
    "createTime": "2013-03-23T13:42:43",
    "closeTime": "2013-03-23T13:42:45",
    "durationInMillis": 2000,
    "createUserId": "aStartUserId",
    "superCaseInstanceId": "aSuperCaseInstanceId",
    "active": true,
    "completed": false,
    "terminated": false,
    "closed": false
  }
]

Get Case Instances Count

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

Method

GET /history/case-instance/count

Parameters

Query Parameters

Name Description
caseInstanceId Filter by case instance id.
caseInstanceIds Filter by case instance ids. Must be a comma-separated list of case instance ids.
caseDefinitionId Filter by the case definition the instances run on.
caseDefinitionKey Filter by the key of the case definition the instances run on.
caseDefinitionKeyNotIn Exclude instances that belong to a set of case definitions. Must be a comma-separated list of case definition keys.
caseDefinitionName Filter by the name of the case definition the instances run on.
caseDefinitionNameLike Filter by case definition names that the parameter is a substring of.
caseInstanceBusinessKey Filter by case instance business key.
caseInstanceBusinessKeyLike Filter by case instance business key that the parameter is a substring of.
createdBefore Restrict to instances that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfter Restrict to instances that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
closedBefore Restrict to instances that were closed before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
closedAfter Restrict to instances that were closed after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdBy Only include case instances that were created by the given user.
superCaseInstanceId Restrict query to all case instances that are sub case instances of the given case instance. Takes a case instance id.
subCaseInstanceId Restrict query to one case instance that has a sub case instance with the given id.
active Only include active case instances. Values may be true or false.
completed Only include completed case instances. Values may be true or false.
terminated Only include terminated case instances. Values may be true or false.
closed Only include closed case instances. Values may be true or false.
notClosed Only include not closed case instances. Values may be true or false.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 case 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/case-instance/count?notClose=true

Response

{
  "count": 1
}

Get Single Historic Detail

Retrieves a single historic detail by id.

Method

GET /history/detail/{id}

Parameters

Path Parameters

Name Description
id The id of the detail.

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

An object having the following properties:

Name Value Description
id String The id of the historic detail.
processInstanceId String The id of the process instance the historic detail belongs to.
activityInstanceId String The id of the execution the historic detail belongs to.
executionId String The id of the execution the historic detail belongs to.
caseInstanceId String The id of the case instance the historic detail belongs to.
caseExecutionId String The id of the case execution the historic detail belongs to.
taskId String The id of the task the historic detail belongs to.
time String The time when this historic detail occurred, has the format yyyy-MM-dd'T'HH:mm:ss.

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

Name Value Description
variableName String The name of the variable which has been updated.
variableInstanceId String The id of the associated variable instance.
variableType String The value type of the variable.
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
revision number The revision of the historic variable update.
errorMessage String An error message in case a Java Serialized Object could not be de-serialized.

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

Name Value Description
fieldId String The id of the form field.
fieldValue String/Number/Boolean/Object The submitted value.

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 /history/detail/someId

Response

Status 200.

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

Get Single Historic Detail (Binary)

Retrieves the content of a single historic variable update by id. Applicable for binary variables.

Method

GET /history/detail/{id}/data

Parameters

Path Parameters

Name Description
id The id of the historic variable update.

Result

Byte stream.

Response codes

Code Media type Description
200 application/octet-stream Request successful.
400 application/json Detail with given id exists but is not a binary variable. See the Introduction for the error response format.
404 application/json Detail with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /history/detail/someId/data

Response

Status 200.

Byte Stream.

Get Historic Details

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

Method

GET /history/detail

Parameters

Query Parameters

Name Description
processInstanceId Filter by process instance id.
executionId Filter by execution id.
activityInstanceId Filter by activity instance id.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by case execution id.
variableInstanceId Filter by variable instance id.
formFields Only include HistoricFormFields. Values may be true or false.
variableUpdates Only include HistoricVariableUpdates. Values may be true or false.
excludeTaskDetails Excludes all task-related HistoricDetails, so only items which have no task id set will be selected. When this parameter is used together with taskId, this call is ignored and task details are not excluded. Values may be true or false.
sortBy Sort the results by a given criterion. Valid values are processInstanceId, variableName, variableType, variableRevision, formPropertyId or time. 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.
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

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

Name Value Description
id String The id of the historic detail.
processInstanceId String The id of the process instance the historic detail belongs to.
activityInstanceId String The id of the execution the historic detail belongs to.
executionId String The id of the execution the historic detail belongs to.
caseInstanceId String The id of the case instance the historic detail belongs to.
caseExecutionId String The id of the case execution the historic detail belongs to.
taskId String The id of the task the historic detail belongs to.
time String The time when this historic detail occurred has the format yyyy-MM-dd'T'HH:mm:ss.

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

Name Value Description
variableName String The name of the variable which has been updated.
variableInstanceId String The id of the associated variable instance.
variableType String The value type of the variable.
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
revision number The revision of the historic variable update.
errorMessage String An error message in case a Java Serialized Object could not be de-serialized.

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

Name Value Description
fieldId String The id of the form field.
fieldValue String/Number/Boolean/Object The submitted value.

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/detail?processInstanceId=aProcInstId

Response

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

Get Historic Details Count

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

Method

GET /history/detail/count

Parameters

Query Parameters

Name Description
processInstanceId Filter by process instance id.
executionId Filter by execution id.
activityInstanceId Filter by activity instance id.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by case execution id.
variableInstanceId Filter by variable instance id.
formFields Only include HistoricFormFields. Values may be true or false.
variableUpdates Only include HistoricVariableUpdates. Values may be true or false.
excludeTaskDetails Excludes all task-related HistoricDetails, so only items which have no task id set will be selected. When this parameter is used together with taskId, this call is ignored and task details are not excluded. 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 details.

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/detail/count?variableName=my_variable

Response

{
  "count": 3
}

Get Historic Activity Statistics

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

Method

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

Parameters

Path Parameters

Name Description
id The id of the process definition.

Query Parameters

Name Description
canceled Whether to include the number of canceled activity instances in the result or not. Valid values are true or false.
finished Whether to include the number of finished activity instances in the result or not. Valid values are true or false.
completeScope Whether to include the number of activity instances which completed a scope in the result or not. Valid values are true or false.
sortBy Sort the results by a given criterion. A valid value is activityId. 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 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 all running instances of the activity.
canceled Number The total number of all canceled instances of the activity. Note: Will be 0 (not null), if canceled activity instances were excluded.
finished Number The total number of all finished instances of the activity. Note: Will be 0 (not null), if finished activity instances were excluded.
completeScope Number The total number of all instances which completed a scope of the activity. Note: Will be 0 (not null), if activity instances which completed a scope were excluded.

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.

Examples

Request with query parameter canceled=true

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

Response

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

Request with query parameter finished=true

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

Response

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

Request with query parameter completeScope=true

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

Response

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

Get Incidents

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

Method

GET /history/incident

Parameters

Query Parameters

Name Description
incidentId Restricts to incidents that have the given id.
incidentType Restricts to incidents that belong to the given incident type.
incidentMessage Restricts to incidents that have the given incident message.
processDefinitionId Restricts to incidents that belong to a process definition with the given id.
processInstanceId Restricts to incidents that belong to a process instance with the given id.
executionId Restricts to incidents that belong to an execution with the given id.
activityId Restricts to incidents that belong to an activity with the given id.
causeIncidentId Restricts to incidents that have the given incident id as cause incident.
rootCauseIncidentId Restricts to incidents that have the given incident id as root cause incident.
configuration Restricts to incidents that have the given parameter set as configuration.
open Restricts to incidents that are open.
deleted Restricts to incidents that are deleted.
resolved Restricts to incidents that are resolved.
sortBy Sort the results lexicographically by a given criterion. Valid values are incidentId, createTime, endTime, incidentType, executionId, activityId, processInstanceId, processDefinitionId, causeIncidentId, rootCauseIncidentId and configuration. 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 incident objects. Each historic incident object has the following properties:

Name Value Description
id String The id of the incident.
processDefinitionId String The id of the process definition this incident is associated with.
processInstanceId String The key of the process definition this incident is associated with.
executionId String The id of the execution this incident is associated with.
createTime String The time this incident happened. Has the format yyyy-MM-dd'T'HH:mm:ss.
endTime String The time this incident has been deleted or resolved. Has the format yyyy-MM-dd'T'HH:mm:ss.
incidentType String The type of incident, for example: failedJobs will be returned in case of an incident which identified a failed job during the execution of a process instance.
activityId String The id of the activity this incident is associated with.
causeIncidentId String The id of the associated cause incident which has been triggered.
rootCauseIncidentId String The id of the associated root cause incident which has been triggered.
configuration String The payload of this incident.
incidentMessage String The message of this incident.
open Boolean If true, this incident is open.
deleted Boolean If true, this incident has been deleted.
resolved Boolean If true, this incident has been resolved.

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/incident?processInstanceId=aProcInstId

Response

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

Get Incidents Count

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

Method

GET /history/incident/count

Parameters

Query Parameters

Name Description
incidentId Restricts to incidents that have the given id.
incidentType Restricts to incidents that belong to the given incident type.
incidentMessage Restricts to incidents that have the given incident message.
processDefinitionId Restricts to incidents that belong to a process definition with the given id.
processInstanceId Restricts to incidents that belong to a process instance with the given id.
executionId Restricts to incidents that belong to an execution with the given id.
activityId Restricts to incidents that belong to an activity with the given id.
causeIncidentId Restricts to incidents that have the given incident id as cause incident.
rootCauseIncidentId Restricts to incidents that have the given incident id as root cause incident.
configuration Restricts to incidents that have the given parameter set as configuration.
open Restricts to incidents that are open.
deleted Restricts to incidents that are deleted.
resolved Restricts to incidents that are resolved.
sortBy Sort the results lexicographically by a given criterion. Valid values are incidentId, createTime, endTime, incidentType, executionId, activityId, processInstanceId, processDefinitionId, causeIncidentId, rootCauseIncidentId and configuration. 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. See the Introduction for the error response format.

Example

Request

GET /history/incident/count?processInstanceId=aProcInstId

Response

{"count": 2}

Get Single Process Instance

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

Method

GET /history/process-instance/{id}

Parameters

Path Parameters

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

Result

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

Name Value Description
id String The id of the process instance.
superProcessInstanceId String The id of the parent process instance, if it exists.
caseInstanceId String The id of the parent case instance, if it 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 canceled during execution.

Response codes

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

Example

Request

GET /history/process-instance/aProcInstId

Response

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

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
processInstanceId Filter by process instance id.
processInstanceIds Filter by process instance ids. Must be a comma-separated list of process instance ids.
processInstanceBusinessKey Filter by process instance business key.
processInstanceBusinessKeyLike Filter by process instance business key that the parameter is a substring of.
superProcessInstanceId Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstanceId Restrict query to one process instance that has a sub process instance with the given id.
caseInstanceId Restrict query to all process instances that are sub process instances of the given case instance. Takes a case 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.
processDefinitionName Filter by the name of the process definition the instances run on.
processDefinitionNameLike Filter by process definition names that the parameter is a substring of.
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, e.g., 2013-01-23T14:42:45.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 it exists.
caseInstanceId String The id of the parent case instance, if it 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 canceled 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

[
  {
    "businessKey": "aKey",
    "caseInstanceId": "aCaseInstanceId",
    "deleteReason": "aDeleteReason",
    "durationInMillis": 2000,
    "endTime": "2013-03-23T13:42:45",
    "id": "aProcInstId",
    "processDefinitionId": "aProcDefId",
    "startActivityId": "aStartActivityId",
    "startTime": "2013-03-23T13:42:43",
    "startUserId": "aStartUserId",
    "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 Process Instances method.

Method

GET /history/process-instance/count

Parameters

Query Parameters

Name Description
processInstanceId Filter by process instance id.
processInstanceIds Filter by process instance ids. Must be a comma-separated list of process instance ids.
processInstanceBusinessKey Filter by process instance business key.
processInstanceBusinessKeyLike Filter by process instance business key that the parameter is a substring of.
superProcessInstanceId Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstanceId Restrict query to one process instance that has a sub process instance with the given id.
caseInstanceId Restrict query to all process instances that are sub process instances of the given case instance. Takes a case 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.
processDefinitionName Filter by the name of the process definition the instances run on.
processDefinitionNameLike Filter by process definition names that the parameter is a substring of.
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, e.g., 2013-01-23T14:42:45.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 Task (Historic)

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

Method

GET /history/task

Parameters

Query Parameters

Name Description
taskId Filter by task id.
taskParentTaskId Filter by parent task id.
processInstanceId Filter by process instance id.
executionId Filter by the id of the execution that executed the task.
processDefinitionId Filter by process definition 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.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by the id of the case execution that executed the task.
caseDefinitionId Filter by case definition id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn Only include tasks which belong to one of the passed and comma-separated activity instance ids.
taskName Restrict to tasks that have the given name.
taskNameLike Restrict to tasks that have a name with the given parameter value as substring.
taskDescription Restrict to tasks that have the given description.
taskDescriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey Restrict to tasks that have the given key.
taskDeleteReason Restrict to tasks that have the given delete reason.
taskDeleteReasonLike Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee Restrict to tasks that the given user is assigned to.
taskAssigneeLike Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner Restrict to tasks that the given user owns.
taskOwnerLike Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority Restrict to tasks that have the given priority.
finished Only include finished tasks. Values may be true or false.
unfinished Only include unfinished tasks. Values may be true or false.
processFinished Only include tasks of finished processes. Values may be true or false.
processUnfinished Only include tasks of unfinished processes. Values may be true or false.
taskDueDate Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskDueDateBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskDueDateAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDate Restrict to tasks that have a followUp date on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDateBefore Restrict to tasks that have a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDateAfter Restrict to tasks that have a followUp date after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results by a given criterion. Valid values are taskId, activityInstanceID, processDefinitionId, processInstanceId, executionId, duration, endTime, startTime, taskName, taskDescription, assignee, owner, dueDate, followUpDate, deleteReason, taskDefinitionKey, priority, caseDefinitionId, caseInstanceId, caseExecutionId. 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 task objects. Each historic task object has the following properties:

Name Value Description
id String The task id.
processDefinitionId String The id of the process definition the task belongs to.
processInstanceId String The id of the process instance the task belongs to.
executionId String The id of the execution the task belongs to.
caseDefinitionId String The id of the case definition the task belongs to.
caseInstanceId String The id of the case instance the task belongs to.
caseExecutionId String The id of the case execution the task belongs to.
activityInstanceId String The id of the activity that this object is an instance of.
name String The task name.
description String The task's description.
deleteReason String The task's delete reason.
owner String The owner's id.
assignee String The assignee's id.
startTime String The time the task was started. Has the format yyyy-MM-dd'T'HH:mm:ss.
endTime String The time the task ended. Has the format yyyy-MM-dd'T'HH:mm:ss.
duration Number The time the task took to finish (in milliseconds).
taskDefinitionKey String The task's key.
priority Number The task's priority.
due String The task's due date. Has the format yyyy-MM-dd'T'HH:mm:ss.
parentTaskId String The id of the parent task, if this task is a subtask.
followUp String The follow-up date for the task. Format yyyy-MM-dd'T'HH:mm:ss.

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/task?taskAssignee=anAssignee&priority=42

Response

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

Get Task Count

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

Method

GET /history/task/count

Parameters

Query Parameters

Name Description
taskId Filter by task id.
taskParentTaskId Filter by parent task id.
processInstanceId Filter by process instance id.
executionId Filter by the id of the execution that executed the task.
processDefinitionId Filter by process definition 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.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by the id of the case execution that executed the task.
caseDefinitionId Filter by case definition id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn Only include tasks which belong to one of the passed and comma-separated activity instance ids.
taskName Restrict to tasks that have the given name.
taskNameLike Restrict to tasks that have a name with the given parameter value as substring.
taskDescription Restrict to tasks that have the given description.
taskDescriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey Restrict to tasks that have the given key.
taskDeleteReason Restrict to tasks that have the given delete reason.
taskDeleteReasonLike Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee Restrict to tasks that the given user is assigned to.
taskAssigneeLike Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner Restrict to tasks that the given user owns.
taskOwnerLike Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority Restrict to tasks that have the given priority.
finished Only include finished tasks. Values may be true or false.
unfinished Only include unfinished tasks. Values may be true or false.
processFinished Only include tasks of finished processes. Values may be true or false.
processUnfinished Only include tasks of unfinished processes. Values may be true or false.
taskDueDate Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskDueDateBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskDueDateAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDate Restrict to tasks that have a followUp date on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDateBefore Restrict to tasks that have a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDateAfter Restrict to tasks that have a followUp date after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 tasks.

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/task/count?taskAssginee=anAssignee&taskPriority=50

Response

{"count": 1}

Get User Operation Log (Historic)

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

Note that the properties of operation log entries are interpreted as restrictions on the entities they apply to. That means, if a single process instance is updated, the field processInstanceId is populated. If a single operation updates all process instances of the same process definition, the field processInstanceId is null (a null restriction is viewed as a wildcard, i.e. matches a process instance with any id) and the field processDefinitionId is populated. This way, it can easily be reconstructed which entities were changed by a user operation.

Method

GET /history/user-operation

Parameters

Query Parameters

Name Description
processDefinitionId Filter by process definition id.
processDefinitionKey Filter by process definition key.
processInstanceId Filter by process instance id.
executionId Filter by execution id.
caseDefinitionId Filter by case definition id.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by case execution id.
taskId Only include operations on this task.
userId Only include operations of this user.
operationId Filter by the id of the operation. This allows fetching of multiple entries which are part of a composite operation.
operationType Filter by the type of the operation like Claim or Delegate.
entityType Filter by the type of the entity that was affected by this operation, possible values are Task, Attachment or IdentityLink.
property Only include operations that changed this property, e.g. owner or assignee
afterTimestamp Restrict to entries that were created after the given timestamp. The timestamp must have the format yyyy-MM-dd'T'HH:mm:ss, e.g. 2014-02-25T14:58:37
beforeTimestamp Restrict to entries that were created before the given timestamp. The timestamp must have the format yyyy-MM-dd'T'HH:mm:ss, e.g. 2014-02-25T14:58:37
sortBy Sort the results by a given criterion. At the moment the query only supports sorting based on the timestamp.
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 operation log entries. Each log entry has the following properties:

Name Value Description
id String The unique identifier of this log entry.
userId String The user who performed this operation.
timestamp String Timestamp of this operation.
operationId String The unique identifier of this operation. A composite operation that changes multiple properties has a common operationId.
operationType String The type of this operation, e.g. Assign, Claim and so on.
entityType String The type of the entity on which this operation was executed, e.g. Task or Attachment.
property String The property changed by this operation.
orgValue String The original value of the changed property.
newValue String The new value of the changed property.
processDefinitionId String If not null, the operation is restricted to entities in relation to this process definition.
processDefinitionKey String If not null, the operation is restricted to entities in relation to process definitions with this key.
processInstanceId String If not null, the operation is restricted to entities in relation to this process instance.
executionId String If not null, the operation is restricted to entities in relation to this execution.
caseDefinitionId String If not null, the operation is restricted to entities in relation to this case definition.
caseInstanceId String If not null, the operation is restricted to entities in relation to this case instance.
caseExecutionId String If not null, the operation is restricted to entities in relation to this case execution.
taskId String If not null, the operation is restricted to entities in relation to this task.

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.

Examples

(1) Request

Gets an operation that updates a single task.

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

Response

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

(2) Request

Gets an operation that updates a multiple process instances with the same key.

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

Response

[{"id": "anUserOperationLogEntryId",
"processDefinitionId": null,
"processDefinitionKey": "aProcessDefinitionKey",
"processInstanceId": null,
"executionId": null,
"taskId": null,
"userId": "demo",
"timestamp": "2014-02-25T14:58:37",
"operationId": "anOperationId",
"operationType": "Suspend",
"entityType": "ProcessInstance",
"property": "suspensionState",
"orgValue": null,
"newValue": "suspended"}]

Get User Operation Log Count

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

Method

GET /history/user-operation/count

Parameters

Query Parameters

Name Description
processDefinitionId Filter by process definition id.
processDefinitionKey Filter by process definition key.
processInstanceId Filter by process instance id.
executionId Filter by execution id.
caseDefinitionId Filter by case definition id.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by case execution id.
taskId Only include operations on this task.
userId Only include operations of this user.
operationId Filter by the id of the operation. This allows fetching of multiple entries which are part of a composite operation.
operationType Filter by the type of the operation like Claim or Delegate.
entityType Filter by the type of the entity that was affected by this operation, possible values are Task, Attachment or IdentityLink.
property Only include operations that changed this property, e.g. owner or assignee
afterTimestamp Restrict to entries that were created after the given timestamp. The timestamp must have the format yyyy-MM-dd'T'HH:mm:ss, e.g. 2014-02-25T14:58:37
beforeTimestamp Restrict to entries that were created before the given timestamp. The timestamp must have the format yyyy-MM-dd'T'HH:mm:ss, e.g. 2014-02-25T14:58:37

Result

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

Name Value Description
count Number The number of matching log entries.

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/user-operation?operationType=Claim&userId=demo

Response

{"count": 1}

Get Single Variable Instance

Retrieves a single historic variable by id.

Method

GET /history/variable-instance/{id}

Parameters

Path Parameters

Name Description
id The id of the variable instance.

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A user object with the following properties:

Name Value Description
id String The id of the variable instance.
name String The name of the variable instance.
type String The value type of the variable.
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
processInstanceId String The id the process instance belongs to.
activityInstanceId String The id of the activity instance in which the variable is valid.
caseInstanceId String The case instance id the variable instance belongs to.
caseExecutionId String The case execution id the variable instance belongs to.
taskId String The id of the task the variable instance belongs to.
errorMessage String An error message in case a Java Serialized Object could not be de-serialized.

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 /history/variable-instance/someId

Response

Status 200.

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

Get Single Variable Instance (Binary)

Retrieves the content of a single historic variable by id. Applicable for variables that are serialized as binary data.

Method

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

Parameters

Path Parameters

Name Description
id The id of the variable instance.

Result

Byte stream.

Response codes

Code Media type Description
200 application/octet-stream Request successful.
400 application/json Variable with given id exists but is not a binary variable. See the Introduction for the error response format.
404 application/json Variable with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /history/variable-instance/someId/data

Response

Status 200.

Byte Stream.

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.
executionIdIn Only include historic variable instances which belong to one of the passed and comma-separated execution ids.
caseInstanceId Filter by the case instance the variable belongs to.
caseExecutionIdIn Only include historic variable instances which belong to one of the passed and comma-separated case execution ids.
taskIdIn Only include historic variable instances which belong to one of the passed and comma-separated task ids.
activityInstanceIdIn Only include historic variable instances which belong to one of the passed and comma-separated activity instance ids.
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.
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

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

Name Value Description
id String The id of the variable instance.
name String The name of the variable instance.
type String The value type of the variable.
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
processInstanceId String The process instance id the variable instance belongs to.
activityInstanceId String The id of the activity instance in which the variable is valid.
caseInstanceId String The case instance id the variable instance belongs to.
caseExecutionId String The case execution id the variable instance belongs to.
taskId String The id of the task the variable instance belongs to.
errorMessage String An error message in case a Java Serialized Object could not be de-serialized.

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

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

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.
executionIdIn Only include historic variable instances which belong to one of the passed and comma-separated execution ids.
caseInstanceId Filter by the case instance the variable belongs to.
caseExecutionIdIn Only include historic variable instances which belong to one of the passed and comma-separated case execution ids.
taskIdIn Only include historic variable instances which belong to one of the passed and comma-separated task ids.
activityInstanceIdIn Only include historic variable instances which belong to one of the passed and comma-separated activity instance ids.

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 Activity Instances (POST)

Query for historic activity instances that fulfill the given parameters.

Method

POST /history/activity-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
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.
canceled Only include canceled activity instances. Values may be true or false.
completeScope Only include activity instances which completed a scope. Values may be true or false.
startedBefore Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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.

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).
canceled Boolean If true, this activity instance is canceled.
completeScope Boolean If true, this activity instance did complete a BPMN 2.0 scope

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/activity-instance

Request body:

{
  "activityType": "userTask",
  "taskAssignee": "peter"
}

Response

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

Get Activity Instances Count (POST)

Query for the number of historic activity instances that fulfill the given parameters.

Method

POST /history/activity-instance/count

Parameters

Request Body

A JSON object with the following properties:

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.
canceled Only include canceled activity instances. Values may be true or false.
completeScope Only include activity instances which completed a scope. Values may be true or false.
startedBefore Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.

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

POST /history/activity-instance/count

Request body:

{
  "activityType": "userTask"
}

Response

{
  "count": 1
}

Get Case Instances (POST)

Query for historic case instances that fulfill the given parameters.

Method

POST /history/case-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
caseInstanceId Filter by case instance id.
caseInstanceIds Filter by case instance ids. Must be a json array of case instance ids.
caseDefinitionId Filter by the case definition the instances run on.
caseDefinitionKey Filter by the key of the case definition the instances run on.
caseDefinitionKeyNotIn Exclude instances that belong to a set of case definitions. Must be a json array of case definition keys.
caseDefinitionName Filter by the name of the case definition the instances run on.
caseDefinitionNameLike Filter by case definition names that the parameter is a substring of.
caseInstanceBusinessKey Filter by case instance business key.
caseInstanceBusinessKeyLike Filter by case instance business key that the parameter is a substring of.
createdBefore Restrict to instances that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfter Restrict to instances that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
closedBefore Restrict to instances that were closed before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
closedAfter Restrict to instances that were closed after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdBy Only include case instances that were created by the given user.
superCaseInstanceId Restrict query to all case instances that are sub case instances of the given case instance. Takes a case instance id.
subCaseInstanceId Restrict query to one case instance that has a sub case instance with the given id.
active Only include active case instances. Values may be true or false.
completed Only include completed case instances. Values may be true or false.
terminated Only include terminated case instances. Values may be true or false.
closed Only include closed case instances. Values may be true or false.
notClosed Only include not closed case instances. Values may be true or false.
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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
sortBy Sort the results by a given criterion. Valid values are instanceId, definitionId, businessKey, createTime, closeTime, 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 case instance objects. Each historic case instance object has the following properties:

Name Value Description
id String The id of the case instance.
businessKey String The business key of the case instance.
caseDefinitionId String The id of the case definition that this case instance belongs to.
createTime String The time the instance was created. Has the format yyyy-MM-dd'T'HH:mm:ss.
closeTime String The time the instance was closed. Has the format yyyy-MM-dd'T'HH:mm:ss.
durationInMillis Number The time the instance took to finish (in milliseconds).
createUserId String The id of the user who created the case instance.
superCaseInstanceId String The id of the parent case instance, if it exists.
active Boolean If true, this case instance is active.
completed Boolean If true, this case instance is completed.
terminated Boolean If true, this case instance is terminated.
closed Boolean If true, this case instance is closed.

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/case-instance

Request body:

{
  "caseInstanceIds": [
    "aCaseInstId",
    "anotherId"
  ],
  "closedAfter": "2013-01-01T00:00:00",
  "closedBefore": "2013-04-01T23:59:59"
}

Response

[
  {
    "id": "aCaseInstId",
    "businessKey": "aKey",
    "caseDefinitionId": "aCaseDefId",
    "createTime": "2013-03-23T13:42:43",
    "closeTime": "2013-03-23T13:42:45",
    "durationInMillis": 2000,
    "createUserId": "aCreateUserId",
    "superCaseInstanceId": "aSuperCaseInstanceId",
    "active": true,
    "completed": false,
    "terminated": false,
    "closed": false
  }
]

Get Case Instances Count (POST)

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

Method

POST /history/case-instance/count

Parameters

Request Body

A JSON object with the following properties:

Name Description
caseInstanceId Filter by case instance id.
caseInstanceIds Filter by case instance ids. Must be a json array of case instance ids.
caseDefinitionId Filter by the case definition the instances run on.
caseDefinitionKey Filter by the key of the case definition the instances run on.
caseDefinitionKeyNotIn Exclude instances that belong to a set of case definitions. Must be a json array of case definition keys.
caseDefinitionName Filter by the name of the case definition the instances run on.
caseDefinitionNameLike Filter by case definition names that the parameter is a substring of.
caseInstanceBusinessKey Filter by case instance business key.
caseInstanceBusinessKeyLike Filter by case instance business key that the parameter is a substring of.
createdBefore Restrict to instances that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfter Restrict to instances that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
closedBefore Restrict to instances that were closed before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
closedAfter Restrict to instances that were closed after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdBy Only include case instances that were created by the given user.
superCaseInstanceId Restrict query to all case instances that are sub case instances of the given case instance. Takes a case instance id.
subCaseInstanceId Restrict query to one case instance that has a sub case instance with the given id.
active Only include active case instances. Values may be true or false.
completed Only include completed case instances. Values may be true or false.
terminated Only include terminated case instances. Values may be true or false.
closed Only include closed case instances. Values may be true or false.
notClosed Only include not closed case instances. Values may be true or false.
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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.

Result

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

Name Value Description
count Number The number of matching historic case 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/case-instance/count

Request body:

{
  "caseInstanceIds": [
    "aCaseInstId",
    "anotherId"
  ],
  "closedAfter": "2013-01-01T00:00:00",
  "closedBefore": "2013-04-01T23:59:59"
}

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 filtering 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
processInstanceId Filter by process instance id.
processInstanceIds Filter by process instance ids. Must be a json array process instance ids.
processInstanceBusinessKey Filter by process instance business key.
processInstanceBusinessKeyLike Filter by process instance business key that the parameter is a substring of.
superProcessInstanceId Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstanceId Restrict query to one process instance that has a sub process instance with the given id.
caseInstanceId Restrict query to all process instances that are sub process instances of the given case instance. Takes a case 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 json array of process definition keys.
processDefinitionName Filter by the name of the process definition the instances run on.
processDefinitionNameLike Filter by process definition names that the parameter is a substring of.
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, e.g., 2013-01-23T14:42:45.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 it exists.
caseInstanceId String The id of the parent case instance, if it 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 canceled 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:

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

Response

[
  {
    "businessKey": "aKey",
    "caseInstanceId": "aCaseInstanceId",
    "deleteReason": "aDeleteReason",
    "durationInMillis": 2000,
    "endTime": "2013-03-23T13:42:45",
    "id": "aProcInstId",
    "processDefinitionId": "aProcDefId",
    "startActivityId": "aStartActivityId",
    "startTime": "2013-03-23T13:42:43",
    "startUserId": "aStartUserId",
    "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 therefore it is 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
processInstanceId Filter by process instance id.
processInstanceIds Filter by process instance ids. Must be a comma-separated list of process instance ids.
processInstanceBusinessKey Filter by process instance business key.
processInstanceBusinessKeyLike Filter by process instance business key that the parameter is a substring of.
superProcessInstanceId Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstanceId Restrict query to one process instance that has a sub process instance with the given id.
caseInstanceId Restrict query to all process instances that are sub process instances of the given case instance. Takes a case 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.
processDefinitionName Filter by the name of the process definition the instances run on.
processDefinitionNameLike Filter by process definition names that the parameter is a substring of.
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, e.g., 2013-01-23T14:42:45.
startedAfter Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedBefore Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
finishedAfter Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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:

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

Response

{
  "count": 1
}

Get Task (Historic) (POST)

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

Method

POST /history/task

Parameters

Query Parameters

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
taskId Filter by task id.
taskParentTaskId Filter by parent task id.
processInstanceId Filter by process instance id.
executionId Filter by the id of the execution that executed the task.
processDefinitionId Filter by process definition 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.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by the id of the case execution that executed the task.
caseDefinitionId Filter by case definition id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn Only include tasks which belong to one of the passed and comma-separated activity instance ids.
taskName Restrict to tasks that have the given name.
taskNameLike Restrict to tasks that have a name with the given parameter value as substring.
taskDescription Restrict to tasks that have the given description.
taskDescriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey Restrict to tasks that have the given key.
taskDeleteReason Restrict to tasks that have the given delete reason.
taskDeleteReasonLike Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee Restrict to tasks that the given user is assigned to.
taskAssigneeLike Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner Restrict to tasks that the given user owns.
taskOwnerLike Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority Restrict to tasks that have the given priority.
finished Only include finished tasks. Values may be true or false.
unfinished Only include unfinished tasks. Values may be true or false.
processFinished Only include tasks of finished processes. Values may be true or false.
processUnfinished Only include tasks of unfinished processes. Values may be true or false.
taskDueDate Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskDueDateBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskDueDateAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDate Restrict to tasks that have a followUp date on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDateBefore Restrict to tasks that have a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDateAfter Restrict to tasks that have a followUp date after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
sortBy Sort the results by a given criterion. Valid values are taskId, activityInstanceID, processDefinitionId, processInstanceId, executionId, duration, endTime, startTime, taskName, taskDescription, assignee, owner, dueDate, followUpDate, deleteReason, taskDefinitionKey and priority, caseDefinitionId, caseInstanceId, caseExecutionId 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 task objects. Each historic task object has the following properties:

Name Value Description
id String The task id.
processDefinitionId String The id of the process definition the task belongs to.
processInstanceId String The id of the process instance the task belongs to.
executionId String The id of the execution the task belongs to.
caseDefinitionId String The id of the case definition the task belongs to.
caseInstanceId String The id of the case instance the task belongs to.
caseExecutionId String The id of the case execution the task belongs to.
activityInstanceId String The id of the activity that this object is an instance of.
name String The task name.
description String The task's description.
deleteReason String The task's delete reason.
owner String The owner's id.
assignee String The assignee's id.
startTime String The time the task was started. Has the format yyyy-MM-dd'T'HH:mm:ss.
endTime String The time the task ended. Has the format yyyy-MM-dd'T'HH:mm:ss.
duration Number The time the task took to finish (in milliseconds).
taskDefinitionKey String The task's key.
priority Number The task's priority.
due String The task's due date. Has the format yyyy-MM-dd'T'HH:mm:ss.
parentTaskId String The id of the parent task, if this task is a subtask.
followUp String The follow-up date for the task. Format yyyy-MM-dd'T'HH:mm:ss.

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/task

Request body:

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

Response

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

Get Task Count (POST)

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

Method

POST /history/task/count

Parameters

Request Body

A JSON object with the following properties:

Name Description
taskId Filter by task id.
taskParentTaskId Filter by parent task id.
processInstanceId Filter by process instance id.
executionId Filter by the id of the execution that executed the task.
processDefinitionId Filter by process definition 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.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by the id of the case execution that executed the task.
caseDefinitionId Filter by case definition id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn Only include tasks which belong to one of the passed and comma-separated activity instance ids.
taskName Restrict to tasks that have the given name.
taskNameLike Restrict to tasks that have a name with the given parameter value as substring.
taskDescription Restrict to tasks that have the given description.
taskDescriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey Restrict to tasks that have the given key.
taskDeleteReason Restrict to tasks that have the given delete reason.
taskDeleteReasonLike Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee Restrict to tasks that the given user is assigned to.
taskAssigneeLike Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner Restrict to tasks that the given user owns.
taskOwnerLike Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority Restrict to tasks that have the given priority.
finished Only include finished tasks. Values may be true or false.
unfinished Only include unfinished tasks. Values may be true or false.
processFinished Only include tasks of finished processes. Values may be true or false.
processUnfinished Only include tasks of unfinished processes. Values may be true or false.
taskDueDate Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskDueDateBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskDueDateAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDate Restrict to tasks that have a followUp date on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDateBefore Restrict to tasks that have a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
taskFollowUpDateAfter Restrict to tasks that have a followUp date after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.

Result

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

Name Value Description
count Number The number of matching historic tasks.

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/task/count

Request body:

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

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 filtering 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.
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

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.
executionIdIn Only include historic variable instances which belong to one of the passed execution ids.
caseInstanceId Filter by the case instance the variable belongs to.
caseExecutionIdIn Only include historic variable instances which belong to one of the passed case execution ids.
taskIdIn Only include historic variable instances which belong to one of the passed task ids.
activityInstanceIdIn Only include historic variable instances which belong to one of the passed activity instance ids.
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
id String The id of the variable instance.
name String The name of the variable instance.
type String The value type of the variable.
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
processInstanceId String The id the process instance belongs to.
activityInstanceId String The id of the activity instance in which the variable is valid.
caseInstanceId String The id of the case instance the variable instance belongs to.
caseExecutionId String The id of the case execution the variable instance belongs to.
taskId String The id of the task the 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. See the Introduction for the error response format.

Example

Request

POST /history/variable-instance

Request body:

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

Response

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

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 therefore it is 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.
executionIdIn Only include historic variable instances which belong to one of the passed execution ids.
caseInstanceId Filter by the case instance the variable belongs to.
caseExecutionIdIn Only include historic variable instances which belong to one of the passed case execution ids.
taskIdIn Only include historic variable instances which belong to one of the passed task ids.
activityInstanceIdIn Only include historic variable instances which belong to one of the passed activity instance ids.

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:

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

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 a 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 Incidents

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

Method

GET /incident

Parameters

Query Parameters

Name Description
incidentId Restricts to incidents that have the given id.
incidentType Restricts to incidents that belong to the given incident type.
incidentMessage Restricts to incidents that have the given incident message.
processDefinitionId Restricts to incidents that belong to a process definition with the given id.
processInstanceId Restricts to incidents that belong to a process instance with the given id.
executionId Restricts to incidents that belong to an execution with the given id.
activityId Restricts to incidents that belong to an activity with the given id.
causeIncidentId Restricts to incidents that have the given incident id as cause incident.
rootCauseIncidentId Restricts to incidents that have the given incident id as root cause incident.
configuration Restricts to incidents that have the given parameter set as configuration.
sortBy Sort the results lexicographically by a given criterion. Valid values are incidentId, incidentTimestamp, incidentType, executionId, activityId, processInstanceId, processDefinitionId, causeIncidentId, rootCauseIncidentId and configuration. 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 incident objects. Each incident object has the following properties:

Name Value Description
id String The id of the incident.
processDefinitionId String The id of the process definition this incident is associated with.
processInstanceId String The key of the process definition this incident is associated with.
executionId String The id of the execution this incident is associated with.
incidentTimestamp String The time this incident happened. Has the format yyyy-MM-dd'T'HH:mm:ss.
incidentType String The type of incident, for example: failedJobs will be returned in case of an incident which identified a failed job during the execution of a process instance.
activityId String The id of the activity this incident is associated with.
causeIncidentId String The id of the associated cause incident which has been triggered.
rootCauseIncidentId String The id of the associated root cause incident which has been triggered.
configuration String The payload of this incident.
incidentMessage String The message of this incident.

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 /incident?processInstanceId=aProcInstId

Response

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

Get Incidents Count

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

Method

GET /incident/count

Parameters

Query Parameters

Name Description
incidentId Restricts to incidents that have the given id.
incidentType Restricts to incidents that belong to the given incident type.
incidentMessage Restricts to incidents that have the given incident message.
processDefinitionId Restricts to incidents that belong to a process definition with the given id.
processInstanceId Restricts to incidents that belong to a process instance with the given id.
executionId Restricts to incidents that belong to an execution with the given id.
activityId Restricts to incidents that belong to an activity with the given id.
causeIncidentId Restricts to incidents that have the given incident id as cause incident.
rootCauseIncidentId Restricts to incidents that have the given incident id as root cause incident.
configuration Restricts to incidents that have the given parameter set as configuration.
sortBy Sort the results lexicographically by a given criterion. Valid values are incidentId, incidentTimestamp, incidentType, executionId, activityId, processInstanceId, processDefinitionId, causeIncidentId, rootCauseIncidentId and configuration. 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. See the Introduction for the error response format.

Example

Request

GET /incident/count?processInstanceId=aProcInstId

Response

{"count": 2}

Get Single Job Definition

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

Method

GET /job-definition/{id}

Parameters

Path Parameters

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

Result

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

Name Value Description
id String The id of the job definition.
processDefinitionId String The id of the process definition this job definition is associated with.
processDefinitionKey String The key of the process definition this job definition is associated with.
activityId String The id of the activity this job definition is associated with.
jobType String The type of the job which is running for this job definition, for example: asynchronous continuation, timer etc.
jobConfiguration String The configuration of a job definition provides details about the jobs which will be created, for example: for timer jobs it is the timer configuration.
suspended Boolean Indicates whether this job definition is suspended or not.

Response codes

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

Example

Request

GET /job-definition/aJobDefinitionId

Response

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

Get Job Definitions

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

Method

GET /job-definition

Parameters

Query Parameters

Name Description
jobDefinitionId Filter by job definition id.
activityIdIn Only include job definitions which belong to one of the passed and comma-separated activity ids.
processDefinitionId Only include job definitions which exist for the given process definition id.
processDefinitionKey Only include job definitions which exist for the given process definition key.
jobType Only include job definitions which exist for the given job type.
jobConfiguration Only include job definitions which exist for the given job configuration.
active Only include active job definitions.
suspended Only include suspended job definitions.
sortBy Sort the results lexicographically by a given criterion. Valid values are jobDefinitionId, activityId, processDefinitionId, processDefinitionKey, jobType and jobConfiguration. 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 definition objects. Each job definition object has the following properties:

Name Value Description
id String The id of the job definition.
processDefinitionId String The id of the process definition this job definition is associated with.
processDefinitionKey String The key of the process definition this job definition is associated with.
activityId String The id of the activity this job definition is associated with.
jobType String The type of the job which is running for this job definition, for example: asynchronous continuation, timer etc.
jobConfiguration String The configuration of a job definition provides details about the jobs which will be created, for example: for timer jobs it is the timer configuration.
suspended Boolean Indicates whether this job definition is suspended or not.

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 /job-definition?activityIdIn=ServiceTask1,ServiceTask2

Response

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

Get Job Definitions Count

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

Method

GET /job-definition/count

Parameters

Query Parameters

Name Description
jobDefinitionId Filter by job definition id.
activityIdIn Only include job definitions which belong to one of the passed and comma-separated activity ids.
processDefinitionId Only include job definitions which exist for the given process definition id.
processDefinitionKey Only include job definitions which exist for the given process definition key.
jobType Only include job definitions which exist for the given job type.
jobConfiguration Only include job definitions which exist for the given job configuration.
active Only include active job definitions.
suspended Only include suspended job definitions.
sortBy Sort the results lexicographically by a given criterion. Valid values are jobDefinitionId, activityId, processDefinitionId, processDefinitionKey, jobType and jobConfiguration. 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. See the Introduction for the error response format.

Example

Request

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

Response

{"count": 2}

Get Job Definitions (POST)

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

Method

POST /job-definition

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
jobDefinitionId Filter by job definition id.
activityIdIn Only include job definitions which belong to one of the passed activity ids.
processDefinitionId Only include job definitions which exist for the given process definition id.
processDefinitionKey Only include job definitions which exist for the given process definition key.
jobType Only include job definitions which exist for the given job type.
jobConfiguration Only include job definitions which exist for the given job configuration.
active Only include active job definitions.
suspended Only include suspended job definitions.
sortBy Sort the results lexicographically by a given criterion. Valid values are jobDefinitionId, activityId, processDefinitionId, processDefinitionKey, jobType and jobConfiguration. 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 definition objects. Each job definition object has the following properties:

Name Value Description
id String The id of the job definition.
processDefinitionId String The id of the process definition this job definition is associated with.
processDefinitionKey String The key of the process definition this job definition is associated with.
activityId String The id of the activity this job definition is associated with.
jobType String The type of the job which is running for this job definition, for example: asynchronous continuation, timer etc.
jobConfiguration String The configuration of a job definition provides details about the jobs which will be created, for example: for timer jobs it is the timer configuration.
suspended Boolean Indicates whether this job definition is suspended or not.

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 /job-definition

Request body:

{
  "activityIdIn": 
    [
      ServiceTask1, ServiceTask2
    ]
}

Response

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

Get Job Definitions Count (POST)

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

Method

POST /job-definition/count

Parameters

Request Body

A JSON object with the following properties:

Name Description
jobDefinitionId Filter by job definition id.
activityIdIn Only include job definitions which belong to one of the passed activity ids.
processDefinitionId Only include job definitions which exist for the given process definition id.
processDefinitionKey Only include job definitions which exist for the given process definition key.
jobType Only include job definitions which exist for the given job type.
jobConfiguration Only include job definitions which exist for the given job configuration.
active Only include active job definitions.
suspended Only include suspended job definitions.
sortBy Sort the results lexicographically by a given criterion. Valid values are jobDefinitionId, activityId, processDefinitionId, processDefinitionKey, jobType and jobConfiguration. 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. See the Introduction for the error response format.

Example

Request

POST /job-definition/count

Request body:

{
  "activityIdIn": 
    [
      ServiceTask1, ServiceTask2
    ]
}

Response

{"count": 2}

Activate/Suspend Job Definition By Id

Activate or suspend a given job definition by id.

Method

PUT /job-definition/{id}/suspended

Parameters

Path Parameters

Name Description
id The id of the job definition 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 job definition. When the value is set to true, the given job definition will be suspended and when the value is set to false, the given job definition will be activated.
includeJobs A Boolean value which indicates whether to activate or suspend also all jobs of the given job definition. When the value is set to true, all jobs of the provided job definition will be activated or suspended and when the value is set to false, the suspension state of all jobs of the provided job definition will not be updated.
executionDate The date on which the given job definition will be activated or suspended. If null, the suspension state of the given job definition is updated immediately. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the provided executionDate parameter doesn't have the expected format. See the Introduction for the error response format.

Example

Request

PUT /job-definition/aJobDefinitionId/suspended

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

Response

Status 204. No content.

Activate/Suspend Job Definitions By Process Definition Id

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

Method

PUT /job-definition/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
processDefinitionId The process definition id of the job definitions to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend all job definitions with the given process definition id. When the value is set to true, all job definitions with the given process definition id will be suspended and when the value is set to false, all job definitions with the given process definition id will be activated.
includeJobs A Boolean value which indicates whether to activate or suspend also all jobs of the job definitions with the given process definition id. When the value is set to true, all jobs of the job definitions with the given process definition id will be activated or suspended and when the value is set to false, the suspension state of all jobs of the job definitions with the given process definition id will not be updated.
executionDate The date on which all job definitions with the given process definition id will be activated or suspended. If null, the suspension state of all job definitions with the given process definition id is updated immediately. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the provided executionDate parameter doesn't have the expected format or if the processDefinitionId parameter is null. See the Introduction for the error response format.

Example

Request

PUT /job-definition/suspended

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

Response

Status 204. No content.

Activate/Suspend Job Definitions By Process Definition Key

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

Method

PUT /job-definition/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
processDefinitionKey The process definition key of the job definitions to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend all job definitions with the given process definition key. When the value is set to true, all job definitions with the given process definition key will be suspended and when the value is set to false, all job definitions with the given process definition key will be activated.
includeJobs A Boolean value which indicates whether to activate or suspend also all jobs of the job definitions with the given process definition key. When the value is set to true, all jobs of the process definitions with the given process definition key will be activated or suspended and when the value is set to false, the suspension state of all jobs of the process definitions with the given process definition key will not be updated.
executionDate The date on which all job definitions with the given process definition key will be activated or suspended. If null, the suspension state of all job definitions with the given process definition key is updated immediately. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the provided executionDate parameter doesn't have the expected format or if the processDefinitionKey parameter is null. See the Introduction for the error response format.

Example

Request

PUT /job-definition/suspended

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

Response

Status 204. No content.

Set Job Retries By Job Definition Id

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

Method

PUT /job-definition/{id}/retries

Parameters

Path Parameters

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

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.
500 application/json The retries could not be set successfully. See the Introduction for the error response format.

Example

Request

PUT /job-definition/aJobDefId/retries

Request body:

{"retries": 3}

Response

Status 204. No content.

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.
jobDefinitionId The id of the associated job definition.
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.
processDefinitionId String The id of the process definition which this job belongs to.
processDefinitionKey String The key of the process definition which this job belongs to.
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.
suspended Boolean A flag indicating whether the job is suspended or not.

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.
jobDefinitionId Only select jobs which exist for the given job definition.
processInstanceId Only select jobs which exist for the given process instance.
executionId Only select jobs which exist for the given execution.
processDefinitionId Filter by the id of the process definition the jobs run on.
processDefinitionKey Filter by the key of the process definition the jobs run on.
activityId Only select jobs which exist for an activity with the given id.
withRetriesLeft Only select jobs which have retries left.
executable Only select jobs which are executable, ie. retries > 0 and due date is null or due date 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 due date 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. operator 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.
active Only include active jobs.
suspended Only include suspended jobs.
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.
jobDefinitionId The id of the associated job definition.
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.
processDefinitionId String The id of the process definition which this job belongs to.
processDefinitionKey String The key of the process definition which this job belongs to.
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.
suspended Boolean A flag indicating whether the job is suspended or not.

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.
jobDefinitionId Only select jobs which exist for the given job definition.
processInstanceId Only select jobs which exist for the given process instance.
executionId Only select jobs which exist for the given execution.
processDefinitionId Filter by the id of the process definition the jobs run on.
processDefinitionKey Filter by the key of the process definition the jobs run on.
activityId Only select jobs which exist for an activity with the given id.
withRetriesLeft Only select jobs which have retries left.
executable Only select jobs which are executable, ie. retries > 0 and due date is null or due date 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 due date 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. operator 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.
active Only include active jobs.
suspended Only include suspended jobs.
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/count?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 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 filtering 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.
jobDefinitionId Only select jobs which exist for the given job definition.
processInstanceId Only select jobs which exist for the given process instance.
executionId Only select jobs which exist for the given execution.
processDefinitionId Filter by the id of the process definition the jobs run on.
processDefinitionKey Filter by the key of the process definition the jobs run on.
activityId Only select jobs which exist for an activity with the given id.
withRetriesLeft Only select jobs which have retries left. Valid value is a boolean.
executable Only select jobs which are executable, ie. retries > 0 and due date is null or due date 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 due date 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. operator 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.
active Only include active jobs.
suspended Only include suspended jobs.
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.
jobDefinitionId The id of the associated job definition.
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.
processDefinitionId String The id of the process definition which this job belongs to.
processDefinitionKey String The key of the process definition which this job belongs to.
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.
suspended Boolean A flag indicating whether the job is suspended or not.

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 therefore it is 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.
jobDefinitionId Only select jobs which exist for the given job definition.
processInstanceId Only select jobs which exist for the given process instance.
executionId Only select jobs which exist for the given execution.
processDefinitionId Filter by the id of the process definition the jobs run on.
processDefinitionKey Filter by the key of the process definition the jobs run on.
activityId Only select jobs which exist for an activity with the given id.
withRetriesLeft Only select jobs which have retries left. Valid value is a boolean.
executable Only select jobs which are executable, ie. retries > 0 and due date is null or due date 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 due date 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. operator 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.
active Only include active jobs.
suspended Only include suspended jobs.
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/count

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}

Activate/Suspend Job By Id

Activate or suspend a given job by id.

Method

PUT /job/{id}/suspended

Parameters

Path Parameters

Name Description
id The id of the job 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 job. When the value is set to true, the given job will be suspended and when the value is set to false, the given job will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.

Example

Request

PUT /job/aJobId/suspended

{
  "suspended" : true
}

Response

Status 204. No content.

Activate/Suspend Jobs By Job Definition Id

Activate or suspend jobs with the given job definition id.

Method

PUT /job/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
jobDefinitionId The job definition id of the jobs to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend all jobs with the given job definition id. When the value is set to true, all jobs with the given job definition id will be suspended and when the value is set to false, all jobs with the given job definition id will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the jobDefinitionId parameter is null. See the Introduction for the error response format.

Example

Request

PUT /job/suspended

{
  "jobDefinitionId" : "aJobDefinitionId",
  "suspended" : true
}

Response

Status 204. No content.

Activate/Suspend Jobs By Process Definition Id

Activate or suspend jobs with the given process definition id.

Method

PUT /job/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
processDefinitionId The process definition id of the jobs to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend all jobs with the given process definition id. When the value is set to true, all jobs with the given process definition id will be suspended and when the value is set to false, all jobs with the given process definition id will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the processDefinitionId parameter is null. See the Introduction for the error response format.

Example

Request

PUT /job/suspended

{
  "processDefinitionId" : "aProcessDefinitionId",
  "suspended" : true
}

Response

Status 204. No content.

Activate/Suspend Jobs By Process Definition Key

Activate or suspend jobs with the given process definition key.

Method

PUT /job/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
processDefinitionKey The process definition key of the jobs to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend all jobs with the given process definition key. When the value is set to true, all jobs with the given process definition key will be suspended and when the value is set to false, all jobs with the given process definition key will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the processDefinitionKey parameter is null. See the Introduction for the error response format.

Example

Request

PUT /job/suspended

{
  "processDefinitionKey" : "aProcessDefinitionKey",
  "suspended" : true
}

Response

Status 204. No content.

Activate/Suspend Jobs By Process Instance Id

Activate or suspend jobs with the given process instance id.

Method

PUT /job/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
processInstanceId The process instance id of the jobs to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend all jobs with the given process instance id. When the value is set to true, all jobs with the given process instance id will be suspended and when the value is set to false, all jobs with the given process instance id will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the processInstanceId parameter is null. See the Introduction for the error response format.

Example

Request

PUT /job/suspended

{
  "processInstanceId" : "aProcessInstanceId",
  "suspended" : true
}

Response

Status 204. No content.

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 due date 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 event or an intermediate message catching event. Internally this maps to the engine's message correlation builder methods MessageCorrelationBuilder#correlate() and MessageCorrelationBuilder#correlateAll(). For more information about the correlation behavior, see the Message Events section of the BPMN 2.0 Implementation Reference.

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 containing 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 with the following properties.

Name Description
value The variable's value.
type The value type of the variable. 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 with the following properties.

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
all A Boolean value that indicates whether the message should be correlated to exactly one entity or multiple entities. If the value is set to false the message will be correlated to exactly one entity (execution or process definition). If the value is set to true the message will be correlated to multiple executions and a process definition that can be instantiated by this message in one go.

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

GET /process-definition/key/{key} (returns the latest version of process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition to be retrieved.
key The key of the process definition (the latest version thereof) 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 deployment id of the process definition.
diagram String The file name of the process definition diagram, if it exists.
suspended Boolean A flag indicating whether the definition is suspended or not.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json The path parameter "key" has no value. See the Introduction for the error response format.
404 application/json Process definition with given id or key does not exist. See the Introduction for the error response format.

Example

Request

GET /process-definition/aProcessDefinitionId

GET /process-definition/key/aProcessDefinitionKey

Response

{"id":"aProcessDefinitionId",
"key":"aProcessDefinitionKey",
"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

GET /process-definition/key/{key}/statistics (returns statistics for the latest version of process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition.
key The key of the process definition (the latest version thereof) to be retrieved.

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 the corresponding number of incidents for each occurred incident type. If it is set to 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 The path parameter "key" has no value.
If both query parameters incidents and incidentsForType were set. See the Introduction for the error response format.
404 application/json Process definition with given key does not exist. See the Introduction for the error response format.

Examples

Request with query parameter failedJobs=true

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

GET /process-definition/key/aProcessDefinitionKey/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

GET /process-definition/key/aProcessDefinitionKey/statistics?incidents=true

Response

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

Request with query parameter incidentsForType=anIncident

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

GET /process-definition/key/aProcessDefinitionKey/statistics?incidentsForType=anIncident

Response

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

Get Process Diagram

Retrieves the diagram of a process definition.

Method

GET /process-definition/{id}/diagram

GET /process-definition/key/{key}/diagram (returns the diagram for the latest version of the process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition.
key The key of the process definition (the latest version thereof) to be retrieved.

Result

The image diagram of this process.

Response codes

Code Media type Description
200 image/png, image/gif, ... (defaults to application/octet-stream if the file suffix is unknown Request successful.
204 The process definition doesn't have an associated diagram.
400 application/json The path parameter "key" has no value or the process definition with given id does not exist. See the Introduction for the error response format.
404 application/json Process definition with given id or key does not exist. See the Introduction for the error response format.

Example

Request

GET /process-definition/invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c/diagram

GET /process-definition/key/invoice/diagram

Get Start Form Variables

Retrieves the start form variables for a process definition. The start form variables take form data specified on the start event into account. If form fields are defined, the variable types and default values of the form fields are taken into account.

Method

GET /process-definition/{id}/form-variables

GET /process-definition/key/{key}/form-variables (returns the form variables for the latest process definition by key).

Parameters

Path Parameters

Name Description
id The id of the process definition to retrieve the variables for.
key The key of the process definition to retrieve the variable for. Will select the latest version of the process definition by key.

Query Parameters

Name Description
variableNames A comma-separated list of variable names. Allows restricting the list of requested variables to the variable names in the list. It is best practice to restrict the list of variables to the variables actually required by the form in order to minimize fetching of data. If the query parameter is ommitted all variables are fetched. If the query parameter contains non-existent variable names, the variable names are ignored.
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A JSON object containing a property for each variable returned. The key is the variable name, the value is a JSON object with the following properties:

Name Value Description
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

Response codes

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

Example

Request

GET /process-definition/anId/form-variables

GET /process-definition/anId/form-variables?variableNames=a,b,c

GET /process-definition/key/aKey/form-variables

Response

{
  "amount": {
      "type": "Integer",
      "value": 5,
      "valueInfo": {}
  },
  "firstName": {
      "type": "String",
      "value": "Jonny"
      "valueInfo": {}
  }

}

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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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 deployment id of the process definition.
diagram String The file name of the process definition diagram, if it exists.
suspended Boolean A flag indicating whether the definition is suspended or not.

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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.

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 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/count?keyLike=Key&version=47

Response

{"count": 1}

Get Rendered Start Form

Retrieves the rendered form for a process definition. This method can be used for getting the HTML rendering of a Generated Task Form.

Method

GET /process-definition/{id}/rendered-form

GET /process-definition/key/{key}/rendered-form (returns the rendered form for the latest version of process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition to get the rendered start form for.
key The key of the process definition (the latest version thereof) to get the rendered start form for.

Result

An HTML response body providing the rendered (generated) form content.

Response codes

Code Media type Description
200 application/xhtml+xml Request successful.
400 application/json The path parameter "key" has no value.
Process definition with given id does not exist or has no form field metadata defined. See the Introduction for the error response format.
404 application/json Process definition with given key does not exist. See the Introduction for the error response format.

Example

Request

GET /process-definition/anId/rendered-form

GET /process-definition/key/aKey/rendered-form

Response

<form class="form-horizontal">
  <div class="control-group">
    <label class="control-label">Customer ID</label>
    <div class="controls">
      <input form-field type="string" name="customerId"></input>
    </div>
  </div>
  <div class="control-group">
    <label class="control-label">Amount</label>
    <div class="controls">
      <input form-field type="number" name="amount"></input>
    </div>
  </div>
</form>

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

GET /process-definition/key/{key}/startForm (returns the key of the start form for the latest version of process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition to get the start form for.
key The key of the process definition (the latest version thereof) to get the start form for.

Result

A JSON object containing the form key.

Name Value Description
key String The form key for the process definition.

Response codes

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

Example

Request

GET /process-definition/anId/startForm

GET /process-definition/key/aKey/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 the corresponding number of incidents for each occurred incident type. If it is set to 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 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":"anIncident", "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":"anIncident", "incidentCount": 22 }
    { "incidentType":"anotherIncident", "incidentCount": 15 }
  ]        
}]

Request with query parameter incidentsForType=anIncident

GET /process-definition/statistics?incidentsForType=anIncident

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":"anIncident", "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

GET /process-definition/key/{key}/xml (returns the XML for the latest version of process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition.
key The key of the process definition (the latest version thereof) to be retrieved

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 The path parameter "key" has no value.
Process definition with given id does not exist. See the Introduction for the error response format.
404 application/json Process definition with given key does not exist. See the Introduction for the error response format.

Example

Request

GET /process-definition/aProcessDefinitionId/xml

GET /process-definition/key/aProcessDefinitionKey/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 and business key may be supplied in the request body.

Method

POST /process-definition/{id}/start

POST /process-definition/key/{key}/start (starts the latest version of process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition to be retrieved.
key The key of the process definition (the latest version thereof) 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. Each key corresponds to a variable name and each value to a variable value. A variable value is a JSON object with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
businessKey The business key the process instance is to be initialized with. The business key uniquely identifies the process instance in the context of the given process definition.
caseInstanceId The case instance id the process instance is to be initialized with.

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.
caseInstanceId String The case instance id of the process instance.
ended Boolean A flag indicating whether the instance is still running or not.
suspended Boolean A flag indicating whether the instance is suspended or not.
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 path parameter "key" has no value.
The instance could not be created due to an invalid variable value, for example if 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.
404 application/json The instance could not be created due to a non existing process definition key. 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

POST /process-definition/key/aProcessDefinitionKey/start

Request body:

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

Response

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

Submit Start Form

Start a process instance using a set of process variables and the business key. If the start event has Form Field Metadata defined, the process engine will perform backend validation for any form fields which have validators defined. See Documentation on Generated Task Forms.

Method

POST /process-definition/{id}/submit-form

POST /process-definition/key/{key}/submit-form (starts the latest version of process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition to submit the form for.
key The key of the process definition (the latest version thereof) to submit the form for.

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. Each key corresponds to a variable name and each value to a variable value. A variable value is a JSON object with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
business key A JSON object containing the business key the process is to be initialized with. The business key uniquely identifies the process instance in the context of the given process definition.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The path parameter "key" has no value.
The variable value or type is invalid, for example if 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.
404 application/json Process definition with given key does not exist. 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/submit-form

POST /process-definition/key/aProcessDefinitionKey/submit-form

Request body:

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

Response

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

Activate/Suspend Process Definition By Id

Activate or suspend a given process definition by id or by latest version of process definition key.

Method

PUT /process-definition/{id}/suspended

PUT /process-definition/key/{key}/suspended (suspend latest version of process definition)

Parameters

Path Parameters

Name Description
id The id of the process definition to activate or suspend.
key The key of the process definition (the latest version thereof) 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 definition. When the value is set to true, the given process definition will be suspended and when the value is set to false, the given process definition will be activated.
includeProcessInstances A Boolean value which indicates whether to activate or suspend also all process instances of the given process definition. When the value is set to true, all process instances of the provided process definition will be activated or suspended and when the value is set to false, the suspension state of all process instances of the provided process definition will not be updated.
executionDate The date on which the given process definition will be activated or suspended. If null, the suspension state of the given process definition is updated immediately. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json The path parameter "key" has no value.
Returned if some of the request parameters are invalid, for example if the provided executionDate parameter doesn't have the expected format. See the Introduction for the error response format.
404 application/json Process definition with given key does not exist. See the Introduction for the error response format.

Example

Request

PUT /process-definition/aProcessDefinitionId/suspended

PUT /process-definition/key/aProcessDefinitionKey/suspended

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

Response

Status 204. No content.

Activate/Suspend Process Definitions By Key

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

Method

PUT /process-definition/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
processDefinitionKey The key of the process definitions to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend all process definitions with the given key. When the value is set to true, all process definitions with the given key will be suspended and when the value is set to false, all process definitions with the given key will be activated.
includeProcessInstances A Boolean value which indicates whether to activate or suspend also all process instances of the process definitions with the given key. When the value is set to true, all process instances of the process definitions with the given key will be activated or suspended and when the value is set to false, the suspension state of all process instances of the process definitions with the given key will not be updated.
executionDate The date on which all process definitions with the given key will be activated or suspended. If null, the suspension state of all process definitions with the given key is updated immediately. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the provided executionDate parameter doesn't have the expected format or if the processDefinitionKey parameter is null. See the Introduction for the error response format.

Example

Request

PUT /process-definition/suspended

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

Response

Status 204. No content.

Get Rendered Task Form

Retrieves the rendered form for a task. This method can be used for getting the HTML rendering of a Generated Task Form.

Method

GET /task/{id}/rendered-form

Parameters

Path Parameters

Name Description
id The id of the task to get the rendered form for.

Result

An HTML response body providing the rendered (generated) form content.

Response codes

Code Media type Description
200 application/xhtml+xml Request successful.
400 application/json The task with the given id does not exist or has no form field metadata defined for this task. See the Introduction for the error response format.

Example

Request

GET /task/anId/rendered-form

Response

<form class="form-horizontal">
  <div class="control-group">
    <label class="control-label">Customer ID</label>
    <div class="controls">
      <input form-field type="string" name="customerId"></input>
    </div>
  </div>
  <div class="control-group">
    <label class="control-label">Amount</label>
    <div class="controls">
      <input form-field type="number" name="amount"></input>
    </div>
  </div>
</form>

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

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

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.
caseInstanceId String The id of the case instance associated with the process instance.
ended Boolean A flag indicating whether the process instance has ended or not. Deprecated: will always be false!
suspended Boolean A flag indicating whether the process instance is suspended or not.

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",
"caseInstanceId":"aCaseInstanceId",
"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 the activity.
activityType String The type of activity (corresponds to the XML element name in the BPMN 2.0, e.g. 'userTask').
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 the activity that this instance enters (asyncBefore job) or leaves (asyncAfter job)
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",
          "activityType": "subProcess",
          "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",
                  "activityId": "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",
                  "activityId": "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.
caseInstanceId Filter by case 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.
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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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.
caseInstanceId String The id of the case instance associated with the process instance.
ended Boolean A flag indicating whether the process instance has ended or not. Deprecated: will always be false!
suspended Boolean A flag indicating whether the process instance is suspended or not.

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",
 "caseInstanceId":"aCaseInstanceId",
 "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.
caseInstanceId Filter by case 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.
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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 from.
varId The name of the variable to get.

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A JSON object with the following properties:

Name Value Description
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 1

Request

GET /process-instance/aProcessInstanceId/variables/aVarName

Response

{
  "value" : {"prop1" : "a", "prop2" : "b"},
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Example 2

Request

GET /process-instance/aProcessInstanceId/variables/aVarName?deserializeValue=false

Response

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

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

Query Parameters

Name Description
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

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 The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 1

Request

GET /process-instance/aProcessInstanceId/variables

Response

{
  "aVariableKey": {
    "value" : {"prop1" : "a", "prop2" : "b"},
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
}

Example 2

Request

GET /process-instance/aProcessInstanceId/variables?deserializeValues=false

Response

{
  "aVariableKey": {
    "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
} 

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 filtering 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.
caseInstanceId Filter by case 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.
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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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.
caseInstanceId String The id of the case instance associated with the process instance.
ended Boolean A flag indicating whether the process instance has ended or not. Deprecated: will always be false!
suspended Boolean A flag indicating whether the process instance is suspended or not.

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",
 "caseInstanceId":"aCaseInstanceId",
 "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 therefore it is 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.
caseInstanceId Filter by case 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.
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.
incidentId Filter by the incident id.
incidentType Filter by the incident type.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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}

Post Single Process Variable (Binary)

Sets the serialized value for a binary variable.

Method

POST /process-instance/{id}/variables/{varId}/data

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 multipart form submit with the following parts:

Form Part Name Content Type Description
data application/octet-stream The binary data to be set.
data application/json

Deprecated: This only works if the REST API is aware of the involved Java classes.

A JSON representation of a serialized Java Object. Form part type (see below) must be provided.

type text/plain

Deprecated: This only works if the REST API is aware of the involved Java classes.

The canonical java type name of the process variable to be set. Example: foo.bar.Customer. If this part is provided, data must be a JSON object which can be converted into an instance of the provided class. The content type of the data part must be application/json in that case (see above).

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

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

POST /process-instance/aProcessInstanceId/variables/aVarName/data

Request body:

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

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

(2) Post the JSON serialization of a Java Class (deprecated):

POST /process-instance/aProcessInstanceId/variables/aVarName/data

Request body:

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

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

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

Response

Status 204. No content.

Update/Delete Process Variables

Updates or deletes the variables of a process instance. Updates precede deletions. 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 with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
deletions An array of String keys of variables to be deleted.

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 if 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 By Id

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, the given process instance will be suspended and when the value is set to false, the given process instance will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.

Example

Request

PUT /process-instance/aProcessInstanceId/suspended

{
  "suspended" : true
}

Response

Status 204. No content.

Activate/Suspend Process Instance By Process Definition Id

Activate or suspend process instances with the given process definition id.

Method

PUT /process-instance/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
processDefinitionId The process definition id of the process instances to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend the process instances with the given process definition id. When the value is set to true, the process instances with the given process definition id will be suspended and when the value is set to false, the process instances with the given process definition id will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the provided processDefinitionId parameter is null. See the Introduction for the error response format.

Example

Request

PUT /process-instance/suspended

{
  "processDefinitionId" : "aProcDefId",
  "suspended" : true
}

Response

Status 204. No content.

Activate/Suspend Process Instance By Process Definition Key

Activate or suspend process instances with the given process definition key.

Method

PUT /process-instance/suspended

Parameters

Request Body

A JSON object with the following properties:

Name Description
processDefinitionKey The process definition key of the process instances to activate or suspend.
suspended A Boolean value which indicates whether to activate or suspend all process instances with the given process definition key. When the value is set to true, all process instances with the given process definition key will be suspended and when the value is set to false, all process instances with the given process definition key will be activated.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if some of the request parameters are invalid, for example if the provided processDefinitionKey parameter is null. See the Introduction for the error response format.

Example

Request

PUT /process-instance/suspended

{
  "processDefinitionKey" : "aProcDefKey",
  "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

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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 1

Request

PUT /process-instance/aProcessInstanceId/variables/aVarName

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

Response

Status 204. No content.

Example 2

Request

PUT /process-instance/aProcessInstanceId/variables/aVarName

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

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.
followUp String The follow-up 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.
caseExecutionId String The id of the case execution the task belongs to.
caseDefinitionId String The id of the case definition the task belongs to.
caseInstanceId String The id of the case instance the task belongs to.
taskDefinitionKey String The task definition key.

Response codes

Code Media type Description
200 application/json Request successful.
200 application/hal+json Request successful. In case of an expected HAL response.
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:49:42",
"followUp:":"2013-01-23T13:44:42",
"delegationState":"RESOLVED",
"description":"aDescription",
"executionId":"anExecution",
"owner":"anOwner",
"parentTaskId":"aParentId",
"priority":42,
"processDefinitionId":"aProcDefId",
"processInstanceId":"aProcInstId",
"caseDefinitionId":"aCaseDefId",
"caseInstanceId":"aCaseInstId",
"caseExecutionId":"aCaseExecution",
"taskDefinitionKey":"aTaskDefinitionKey"}

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.

Security Consideration

There are several query parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.

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.
processInstanceBusinessKeyLike Restrict to tasks that have a process instance business key that has the parameter value as a substring.
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.
processDefinitionNameLike Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId Restrict to tasks that belong to an execution with the given id.
caseInstanceId Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId Restrict to tasks that belong to a case definition with the given id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
caseDefinitionNameLike Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn Only include tasks which belong to one of the passed and comma-separated activity instance ids.
assignee Restrict to tasks that the given user is assigned to.
assigneeExpression Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
owner Restrict to tasks that the given user owns.
ownerExpression Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup Only include tasks that are offered to the given group.
candidateGroupExpression Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
candidateUser Only include tasks that are offered to the given user.
candidateUserExpression Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
involvedUser Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g. the user is the assignee).
involvedUserExpression Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
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, e.g., 2013-01-23T14:42:45.
dueDateExpression Restrict to tasks that are due on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
dueAfterExpression Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
dueBeforeExpression Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUp Restrict to tasks that have a followUp date on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpDateExpression Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpAfter Restrict to tasks that have a followUp date after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpAfterExpression Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBefore Restrict to tasks that have a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpBeforeExpression Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBeforeOrNotExistent Restrict to tasks that have no followUp date or a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45. The typical use case is to query all "active" tasks for a user for a given date.
followUpBeforeOrNotExistentExpression Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
created Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45. Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero milliseconds.
createdOnExpression Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdAfter Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfterExpression Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdBefore Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdBeforeExpression Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
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.
candidateGroupsExpression Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to java.util.List of Strings.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
caseInstanceVariables Only include tasks that belong to case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are instanceId, caseInstanceId, dueDate, executionId, caseExecutionId,assignee, created, description, id, name, nameCaseInsensitive 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.
followUp String The follow-up date for the task. 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.
caseExecutionId String The id of the case execution the task belongs to.
caseDefinitionId String The id of the case definition the task belongs to.
caseInstanceId String The id of the case instance the task belongs to.
taskDefinitionKey String The task's key.

Response codes

Code Media type Description
200 application/json Request successful.
200 application/hal+json Request successful. In case of an expected HAL response.
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:49:42",
 "followUp:":"2013-01-23T13:44:42",
 "delegationState":"RESOLVED",
 "description":"aDescription",
 "executionId":"anExecution",
 "owner":"anOwner",
 "parentTaskId":"aParentId",
 "priority":42,
 "processDefinitionId":"aProcDefId",
 "processInstanceId":"aProcInstId",
 "caseDefinitionId":"aCaseDefId",
 "caseInstanceId":"aCaseInstId",
 "caseExecutionId":"aCaseExecution",
 "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.

Security Consideration

There are several query parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.

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.
processInstanceBusinessKeyLike Restrict to tasks that have a process instance business key that has the parameter value as a substring.
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.
processDefinitionNameLike Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId Restrict to tasks that belong to an execution with the given id.
caseInstanceId Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId Restrict to tasks that belong to a case definition with the given id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
caseDefinitionNameLike Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn Only include tasks which belong to one of the passed and comma-separated activity instance ids.
assignee Restrict to tasks that the given user is assigned to.
assigneeExpression Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
owner Restrict to tasks that the given user owns.
ownerExpression Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup Only include tasks that are offered to the given group.
candidateGroupExpression Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
candidateUser Only include tasks that are offered to the given user.
candidateUserExpression Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
involvedUser Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee).
involvedUserExpression Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
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, e.g., 2013-01-23T14:42:45.
dueDateExpression Restrict to tasks that are due on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
dueAfterExpression Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
dueBeforeExpression Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUp Restrict to tasks that have a followUp date on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpDateExpression Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpAfter Restrict to tasks that have a followUp date after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpAfterExpression Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBefore Restrict to tasks that have a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpBeforeExpression Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBeforeOrNotExistent Restrict to tasks that have no followUp date or a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpBeforeOrNotExistentExpression Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
created Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45. Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero milliseconds.
createdOnExpression Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdAfter Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfterExpression Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdBefore Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdBeforeExpression Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
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.
candidateGroupsExpression Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to java.util.List of Strings.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
caseInstanceVariables Only include tasks that belong to case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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. See the Introduction for the error response format.

Example

Request

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

Response

{"count":1}

Get Tasks (POST)

Query for tasks that fulfill a given filter. This method is slightly more powerful than the GET query because it allows filtering 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.

Security Consideration

There are several query parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.

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.
processInstanceBusinessKeyLike Restrict to tasks that have a process instance business key that has the parameter value as a substring.
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.
processDefinitionNameLike Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId Restrict to tasks that belong to an execution with the given id.
caseInstanceId Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId Restrict to tasks that belong to a case definition with the given id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
caseDefinitionNameLike Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn Only include tasks which belong to one of the passed activity instance ids.
assignee Restrict to tasks that the given user is assigned to.
assigneeExpression Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
owner Restrict to tasks that the given user owns.
ownerExpression Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup Only include tasks that are offered to the given group.
candidateGroupExpression Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
candidateUser Only include tasks that are offered to the given user.
candidateUserExpression Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
involvedUser Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee).
involvedUserExpression Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
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, e.g., 2013-01-23T14:42:45.
dueDateExpression Restrict to tasks that are due on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
dueAfterExpression Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
dueBeforeExpression Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpDate Restrict to tasks that have a followUp date on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpDateExpression Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpAfter Restrict to tasks that have a followUp date after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpAfterExpression Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBefore Restrict to tasks that have a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpBeforeExpression Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBeforeOrNotExistent Restrict to tasks that have no followUp date or a followUp date before the given date. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBeforeOrNotExistentExpression Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdOn Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45. Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero milliseconds.
createdOnExpression Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdAfter Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfterExpression Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdBefore Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdBeforeExpression Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
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"].
candidateGroupsExpression Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to java.util.List of Strings.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
caseInstanceVariables Only include tasks that belong to case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
key and value may not contain underscore or comma characters.
sortBy Sort the results lexicographically by a given criterion. Valid values are instanceId, caseInstanceId, dueDate, executionId, caseExecutionId,assignee, created, description, id, name, nameCaseInsensitive 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.
followUp String The follow-up date for the task. 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.
caseExecutionId String The id of the case execution the task belongs to.
caseDefinitionId String The id of the case definition the task belongs to.
caseInstanceId String The id of the case 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:49:42",
 "followUp:":"2013-01-23T13:44:42",
 "delegationState":"RESOLVED",
 "description":"aDescription",
 "executionId":"anExecution",
 "owner":"anOwner",
 "parentTaskId":"aParentId",
 "priority":10,
 "processDefinitionId":"aProcDefId",
 "processInstanceId":"aProcInstId",
 "caseDefinitionId":"aCaseDefId",
 "caseInstanceId":"aCaseInstId",
 "caseExecutionId":"aCaseExecution",
 "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.

Security Consideration

There are several query parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.

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.
processInstanceBusinessKeyLike Restrict to tasks that have a process instance business key that has the parameter value as a substring.
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.
processDefinitionNameLike Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId Restrict to tasks that belong to an execution with the given id.
caseInstanceId Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId Restrict to tasks that belong to a case definition with the given id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
caseDefinitionNameLike Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn Only include tasks which belong to one of the passed activity instance ids.
assignee Restrict to tasks that the given user is assigned to.
assigneeExpression Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
owner Restrict to tasks that the given user owns.
ownerExpression Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup Only include tasks that are offered to the given group.
candidateGroupExpression Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
candidateUser Only include tasks that are offered to the given user.
candidateUserExpression Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
involvedUser Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee).
involvedUserExpression Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
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, e.g., 2013-01-23T14:42:45.
dueDateExpression Restrict to tasks that are due on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueAfter Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
dueAfterExpression Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueBefore Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
dueBeforeExpression Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpDate Restrict to tasks that have a followUp date on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpDateExpression Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpAfter Restrict to tasks that have a followUp date after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpAfterExpression Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBefore Restrict to tasks that have a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpBeforeExpression Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBeforeOrNotExistent Restrict to tasks that have no followUp date or a followUp date before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
followUpBeforeOrNotExistentExpression Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdOn Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45. Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero milliseconds.
createdOnExpression Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdAfter Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdAfterExpression Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdBefore Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss, e.g., 2013-01-23T14:42:45.
createdBeforeExpression Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
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"].
candidateGroupsExpression Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to java.util.List of Strings.
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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
caseInstanceVariables Only include tasks that belong to case 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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. 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}

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

Claim Task

Claim a task for a specific user.

Note: The difference with set a assignee is that here a check is performed to see 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.

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.

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 with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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

Submit Task Form

Complete a task and update process variables using a form submit. There are two difference between this method and the complete method:

  • If the task is in state PENDING - ie. has been delegated before, it is not completed but resolved. Otherwise it will be completed.
  • If the task has Form Field Metadata defined, the process engine will perform backend validation for any form fields which have validators defined. See the Generated Task Forms section of the User Guide for more information.

Method

POST /task/{id}/submit-form

Parameters

Path Parameters

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

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 and has the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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/submit-form

Request body:

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

Response

Status 204. No content.

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 with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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

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 if the task already has 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 for.

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.

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 Task Comments

Gets the comments for a task.

Method

GET /task/{id}/comment

Parameters

Path Parameters

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

Result

A JSON object containing a list of task comments.

Name Value Description
id String The id of the task comment.
userId String The id of the user who created the comment.
taskId String The id of the task to which the comment belongs.
time Date The time when the comment was created.
message String The content of the comment.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json No task exists for the given task id. See the Introduction for the error response format.

Example

Request

GET /task/aTaskId/comment

Response

[
  {
    "id": "commentId",
    "userId": "userId",
    "taskId": "aTaskId",
    "time": "2013-01-02T21:37:03",
    "message": "message"
  },
  {
    "id": "anotherCommentId",
    "userId": "anotherUserId",
    "taskId": "aTaskId",
    "time": "2013-02-23T20:37:43",
    "message": "anotherMessage"
  },
  {
    "id": "yetAnotherCommentId",
    "userId": "yetAnotherUserId",
    "taskId": "aTaskId",
    "time": "2013-04-21T10:15:23",
    "message": "yetAnotherMessage"
  }
]

Get Single Task Comment

Retrieves a single task comment by task id and comment id.

Method

GET /task/{id}/comment/{commentId}

Parameters

Path Parameters

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

Result

A JSON object corresponding to the Comment interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the task comment.
userId String The id of the user who created the comment.
taskId String The id of the task to which the comment belongs.
time Date The time when the comment was created.
message String The content of the comment.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json The task or comment with given task and comment id do not exist, or the history of the engine is disabled. See the Introduction for the error response format.

Example

Request

GET /task/aTaskId/comment/aTaskCommentId

Response

{
  "id": "aTaskCommentId",
  "userId": "userId",
  "taskId": "aTaskId",
  "time": "2013-01-02T21:37:03",
  "message": "comment content"
}

Post Task Comment

Create a comment for a task.

Method

POST /task/{id}/comment/create

Parameters

Path Parameters

Name Description
id The id of the task to add the comment to.

Request Body

A JSON object with the following properties:

Name Description
message The message of the task comment to create. Has to be of type String.

Result

A JSON object representing the newly created comment. Its structure corresponds to the Comment interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the task comment.
userId String The id of the user who created the comment.
taskId String The id of the task to which the comment belongs.
time Date The time when the comment was created.
message String The content of the comment.
links List Link to the newly created task comment with method, href and rel.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json The task does not exist or no comment message was submitted. See the Introduction for the error response format.
403 application/json The history of the engine is disabled. See the Introduction for the error response format.

Example

Request

Post data for a new task comment:

POST /task/aTaskId/comment/create

{"message": "a task comment"}

Response

Status 200.

{
  "links": [
    {
      "method": "GET",
      "href": "http://localhost:38080/rest-test/task/aTaskId/comment/aTaskCommentId",
      "rel": "self"
    }
  ],
  "id": "aTaskCommentId",
  "userId": "userId",
  "taskId": "aTaskId",
  "time": "2013-01-02T21:37:03",
  "message": "comment message"
}

Get Task Attachments

Gets the attachments for a task.

Method

GET /task/{id}/attachment

Parameters

Path Parameters

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

Result

A JSON object containing a list of task attachments.

Name Value Description
id String The id of the task attachment.
name String The name of the task attachment.
taskId String The id of the task to which the comment belongs.
description String The description of the task attachment.
type String Indication of the type of content that this attachment refers to. Can be MIME type or any other indication.
url String The url to the remote content of the task attachment.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json No task exists for the given task id. See the Introduction for the error response format.

Example

Request

GET /task/aTaskId/attachment

Response

[
  {
    "id": "attachmentId",
    "name": "attachmentName",
    "taskId": "aTaskId",
    "description": "attachmentDescription",
    "type": "attachmentType",
    "url": "http://my-attachment-content-url.de"
  },
  {
    "id": "anotherAttachmentId",
    "name": "anotherAttachmentName",
    "taskId": "aTaskId",
    "description": "anotherAttachmentDescription",
    "type": "anotherAttachmentType",
    "url": "http://my-another-attachment-content-url.de"
  },
  {
    "id": "yetAnotherAttachmentId",
    "name": "yetAnotherAttachmentName",
    "taskId": "aTaskId",
    "description": "yetAnotherAttachmentDescription",
    "type": "yetAnotherAttachmentType",
    "url": "http://yet-another-attachment-content-url.de"
  }
]

Get Single Task Attachment

Retrieves a single task attachment by task id and attachment id.

Method

GET /task/{id}/attachment/{attachmentId}

Parameters

Path Parameters

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

Result

A JSON object corresponding to the Attachment interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the task attachment.
name String The name of the task attachment.
taskId String The id of the task to which the comment belongs.
description String The description of the task attachment.
type String Indication of the type of content that this attachment refers to. Can be MIME type or any other indication.
url String The url to the remote content of the task attachment.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json The attachment for given task and attachment id does not exist or the history of the engine is disabled. See the Introduction for the error response format.

Example

Request

GET /task/aTaskId/attachment/aTaskAttachmentId

Response

{
    "id": "attachmentId",
    "name": "attachmentName",
    "taskId": "aTaskId",
    "description": "attachmentDescription",
    "type": "attachmentType",
    "url": "http://my-attachment-content-url.de"
}

Post Task Attachment

Create an attachment for a task.

Method

POST /task/{id}/attachment/create

Parameters

Path Parameters

Name Description
id The id of the task to add the attachment to.

Request Body

A multipart form submit with the following parts:

Form Part Name Content Type Description
attachment-name text/plain The name of the attachment.
attachment-description text/plain The description of the attachment.
attachment-type text/plain The type of the attachment.
url text/plain The url to the remote content of the attachment.
content text/plain The content of the attachment.

Result

A JSON object corresponding to the Attachment interface in the engine. Its properties are as follows:

Name Value Description
id String The id of the task attachment.
name String The name of the task attachment.
taskId String The id of the task to which the comment belongs.
description String The description of the task attachment.
type String Indication of the type of content that this attachment refers to. Can be MIME type or any other indication.
url String The url to the remote content of the task attachment.

Response codes

Code Media type Description
200 application/json Request successful.
400 application/json The task does not exists or task id is null. No content or url to remote content exists. See the Introduction for the error response format.
403 application/json The history of the engine is disabled. See the Introduction for the error response format.

Example

Request

Post data for a new task attachment:

POST /task/aTaskId/attachment/create

------------------------------925df49a954b
Content-Disposition: form-data; name="url"

http://my-attachment-content-url.de
------------------------------925df49a954b
Content-Disposition: form-data; name="attachment-name"

attachmentName
------------------------------925df49a954b
Content-Disposition: form-data; name="attachment-description"

attachmentDescription
------------------------------925df49a954b
Content-Disposition: form-data; name="attachment-type"

attachmentType
------------------------------925df49a954b--

Response

Status 200.

{
  "links": [
    {
      "method": "GET",
      "href": "http://localhost:38080/rest-test/task/aTaskId/attachment/aTaskAttachmentId",
      "rel": "self"
    }
  ],
    "id": "attachmentId",
    "name": "attachmentName",
    "taskId": "aTaskId",
    "description": "attachmentDescription",
    "type": "attachmentType",
    "url": "http://my-attachment-content-url.de"
}

Get Single Task Attachment Content (binary)

Retrieves the binary content of a single task attachment by task id and attachment id.

Method

GET /task/{id}/attachment/{attachmentId}/data

Parameters

Path Parameters

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

Result

Byte Stream.

Response codes

Code Media type Description
200 application/json Request successful.
404 application/json The attachment content for given task and attachment id does not exist or the history of the engine is disabled. See the Introduction for the error response format.

Example

Request

GET /task/aTaskId/attachment/aTaskAttachmentId/data

Response

Status 200. Byte Stream.

Delete Task Attachment

Removes an attachment from a task.

Method

DELETE /task/{id}/attachment/{attachmentId}

Parameters

Path Parameters

Name Description
id The id of the task.
attachmentId The id of the attachment to be removed.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
403 application/json The history of the engine is disabled. See the Introduction for the error response format.
404 application/json Task attachment for given task id and attachment id does not exist. See the Introduction for the error response format.

Example

Request

DELETE /task/aTaskId/attachment/aTaskAttachmentId

Response

Status 204. No content.

Get Local Task Variable

Retrieves a variable from the context of a given task.

Method

GET /task/{id}/localVariables/{varId}

Parameters

Path Parameters

Name Description
id The id of the task to retrieve the variable from.
varId The name of the variable to get.

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A JSON object with the following properties:

Name Value Description
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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.
500 application/json Task id is null or does not exist. See the Introduction for the error response format.

Example 1

Request

GET /task/aTaskId/localVariables/aVarName

Response

{
  "value" : {"prop1" : "a", "prop2" : "b"},
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Example 2

Request

GET /task/aTaskId/localVariables/aVarName?deserializeValue=false

Response

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Get Local Task Variables

Retrieves all variables of a given task.

Method

GET /task/{id}/localVariables

Parameters

Path Parameters

Name Description
id The id of the task to retrieve the variables from.

Query Parameters

Name Description
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

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 The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

Response codes

Code Media type Description
200 application/json Request successful.
500 application/json Task id is null or does not exist. See the Introduction for the error response format.

Example

Request

GET /task/aTaskId/localVariables

Response

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

Example 1

Request

GET /task/aTaskId/localVariables

Response

{
  "aVariableKey": {
    "value" : {"prop1" : "a", "prop2" : "b"},
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
}

Example 2

Request

GET /task/aTaskId/localVariables?deserializeValues=false

Response

{
  "aVariableKey": {
    "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
    "type" : "Object",
    "valueInfo" : {
      "objectTypeName": "com.example.MyObject",
      "serializationDataFormat": "application/xml"
    }
  }
} 

Update/Delete Local Task Variables

Updates or deletes the variables in the context of a task. Updates precede deletions. So, if a variable is updated AND deleted, the deletion overrides the update.

Method

POST /task/{id}/localVariables

Parameters

Path Parameters

Name Description
id The id of the task 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 with the following properties:

Name Description
value The variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
deletions An array of String keys of variables to be deleted.

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 Update or delete could not be executed because the task is null or does not exist.

Example

Request

POST /task/aTaskId/localVariables

Request body:

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

Response

Status 204. No content.

Put Local Task Variable

Sets a variable in the context of a given task.

Method

PUT /task/{id}/localVariables/{varId}

Parameters

Path Parameters

Name Description
id The id of the task 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 variable's value. For variables of type Object, the serialized value has to be submitted as a String value.
type The value type of the variable.
valueInfo

A JSON object containing additional, value-type-dependent properties.

For serialized variables of type Object, the following properties can be provided:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

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 if 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 variable name is null. Task id is null or does not exist. See the Introduction for the error response format.

Example 1

Request

PUT /task/aTaskId/localVariables/aVarName

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

Response

Status 204. No content.

Example 2

Request

PUT /task/aTaskId/localVariables/aVarName

{
  "value" : "<myObj><prop1>a</prop1><prop2>b</prop2></myObj>",
  "type" : "Object",
  "valueInfo" : {
    "objectTypeName": "com.example.MyObject",
    "serializationDataFormat": "application/xml"
  }
}

Response

Status 204. No content.

Post Local Task Variable (Binary)

Sets the serialized value for a binary variable.

Method

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

Parameters

Path Parameters

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

Request Body

A multipart form submit with the following parts:

Form Part Name Content Type Description
data application/octet-stream The binary data to be set.
data application/json

Deprecated: This only works if the REST API is aware of the involved Java classes.

A JSON representation of a serialized Java Object. Form part type (see below) must be provided.

type text/plain

Deprecated: This only works if the REST API is aware of the involved Java classes.

The canonical java type name of the variable to be set. Example: foo.bar.Customer. If this part is provided, data must be a JSON object which can be converted into an instance of the provided class. The content type of the data part must be application/json in that case (see above).

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 if 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 Variable name is null. Task id is null or does not exist. See the Introduction for the error response format.

Example

Request

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

POST /task/aTaskId/localVariables/aVarName/data

------------------------------354ddb6baeff
Content-Disposition: form-data; name="data"; filename="image.png"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

<<Byte Stream ommitted>>
------------------------------354ddb6baeff--

(2) Post the JSON serialization of a Java Class (deprecated):

POST /task/aTaskId/localVariables/aVarName/data

------------------------------1e838f8f632a
Content-Disposition: form-data; name="type"
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit

java.util.ArrayList<java.lang.Object>
------------------------------1e838f8f632a
Content-Disposition: form-data; name="data"
Content-Type: application/json; charset=US-ASCII
Content-Transfer-Encoding: 8bit

["foo","bar"]
------------------------------1e838f8f632a--

Response

Status 204. No content.

Delete Local Task Variable

Removes a local variable from a task.

Method

DELETE /task/{id}/localVariables/{varId}

Parameters

Path Parameters

Name Description
id The id of the task.
varId The name of the variable to be removed.

Result

This method returns no content.

Response codes

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

Example

Request

DELETE /task/aTaskId/localVariables/aVarName

Response

Status 204. No content.

Get Task Form Variables

Retrieves the form variables for a task. The form variables take form data specified on the task into account. If form fields are defined, the variable types and default values of the form fields are taken into account.

Method

GET /task/{id}/form-variables

Parameters

Path Parameters

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

Query Parameters

Name Description
variableNames A comma-separated list of variable names. Allows restricting the list of requested variables to the variable names in the list. It is best practice to restrict the list of variables to the variables actually required by the form in order to minimize fetching of data. If the query parameter is ommitted all variables are fetched. If the query parameter contains non-existent variable names, the variable names are ignored.
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A JSON object containing a property for each variable returned. The key is the variable name, the value is a JSON object with the following properties:

Name Value Description
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
type String The value type of the variable.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.

Response codes

Code Media type Description
200 application/xhtml+xml Request successful.
404 application/json Task id is null or does not exist. See the Introduction for the error response format.

Example

Request

GET /task/anId/form-variables

GET /task/anId/form-variables?variableNames=a,b,c

Response

{
  "amount": {
      "type": "integer",
      "value": 5,
      "valueInfo": {}
  },
  "firstName": {
      "type": "String",
      "value": "Jonny",
      "valueInfo": {}
  }

}

Create Task

Create a new task.

Method

POST /task/create

Parameters

Request Body

A JSON object with the following properties:

Name Type Description
id String The id of the task.
name String The task name.
description String The task description.
assignee String The user to assign to this task.
owner String The owner of the task.
delegationState String The delegation state of the task. Corresponds to the DelegationState enum in the engine. Possible values are RESOLVED and PENDING.
due String The due date for the task. Format yyyy-MM-dd'T'HH:mm:ss.
followUp String The follow-up date for the task. Format yyyy-MM-dd'T'HH:mm:ss.
priority Number The priority of the task.
parentTaskId String The id of the parent task, if this task is a subtask.
caseInstanceId String The id of the case instance the task belongs to.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if a not valid delegationState is supplied. See the Introduction for the error response format.

Example

Request

POST /task/create

Request body:

{
  "id": "aTaskId",
  "name": "My Task",
  "description": "This have to be done very urgent",
  "priority" : 30,
  "assignee" : "peter",
  "owner" : "mary",
  "delegationState" : "PENDING",
  "due" : "2014-08-30T10:00:00",
  "followUp" : "2014-08-25T10:00:00",
  "parentTaskId" : "aParentTaskId",
  "caseInstanceId" : "aCaseInstanceId"
}

Response

Status 204. No content.

Update a Task

Updates a task.

Method

PUT /task/{id}/

Parameters

Request Body

A JSON object with the following properties:

Name Type Description
name String The task name.
description String The task description.
assignee String The user to assign to this task.
owner String The owner of the task.
delegationState String The delegation state of the task. Corresponds to the DelegationState enum in the engine. Possible values are RESOLVED and PENDING.
due String The due date for the task. Format yyyy-MM-dd'T'HH:mm:ss.
followUp String The follow-up date for the task. Format yyyy-MM-dd'T'HH:mm:ss.
priority Number The priority of the task.
parentTaskId String The id of the parent task, if this task is a subtask.
caseInstanceId String The id of the case instance the task belongs to.

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
400 application/json Returned if a not valid delegationState is supplied. See the Introduction for the error response format.
404 application/json If the corresponding task cannot be found

Example

Request

PUT /task/aTaskId/

Request body:

{
  "name": "My Task",
  "description": "This have to be done very urgent",
  "priority" : 30,
  "assignee" : "peter",
  "owner" : "mary",
  "delegationState" : "PENDING",
  "due" : "2014-08-30T10:00:00",
  "followUp" : "2014-08-25T10:00:00",
  "parentTaskId" : "aParentTaskId",
  "caseInstanceId" : "aCaseInstanceId"
}

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.

Result

This method returns no content.

Response codes

Code Media type Description
200 application/json Request successful.
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
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 or not may depend on various things, including the user's authorizations to interact with this resource and the internal 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 (ie. 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 property: password (String).

Result

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
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 (ie. the user with passed id as path parameter).

Result

This method returns no content.

Response codes

Code Media type Description
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
204 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

Status 204. No content.

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

This method returns no content.

Response codes

Code Media type Description
204 Request successful.
403 application/json Identity service is read-only (Cannot modify users / groups / memberships).
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

Status 204. No content.

Get Single Variable Instance

Retrieves a single variable by id.

Method

GET /variable-instance/{id}

Parameters

Path Parameters

Name Description
id The id of the variable instance.

Query Parameters

Name Description
deserializeValue

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

A json object with the following properties:

Name Value Description
id String The id of the variable instance.
name String The name of the variable instance.
type String The value type of the variable.
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValue parameter.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
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.
caseInstanceId String The id of the case instance that this variable instance belongs to.
caseExecutionId String The id of the case 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.
errorMessage String An error message in case a Java Serialized Object could not be de-serialized.

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 /variable-instance/someId

Response

Status 200.

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

Get Single Variable Instance (Binary)

Retrieves the content of a single variable by id. Applicable for byte array variables.

Method

GET /variable-instance/{id}/data

Parameters

Path Parameters

Name Description
id The id of the variable instance.

Result

Byte stream.

Response codes

Code Media type Description
200 application/octet-stream Request successful.
400 application/json Variable with given id exists but does not serialize as binary data. See the Introduction for the error response format.
404 application/json Variable with given id does not exist. See the Introduction for the error response format.

Example

Request

GET /variable-instance/someId/data

Response

Status 200.

Byte Stream.

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 belong to one of the passed and comma-separated process instance ids.
executionIdIn Only include variable instances which belong to one of the passed and comma-separated execution ids.
caseInstanceIdIn Only include variable instances which belong to one of the passed case instance ids.
caseExecutionIdIn Only include variable instances which belong to one of the passed case execution ids.
taskIdIn Only include variable instances which belong to one of the passed and comma-separated task ids.
activityInstanceIdIn Only include variable instances which belong 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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.
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

Result

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

Name Value Description
id String The id of the variable instance.
name String The name of the variable instance.
type String The value type of the variable.
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
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.
caseInstanceId String The id of the case instance that this variable instance belongs to.
caseExecutionId String The id of the case 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

[
  {
    "id": "someId",
    "name": "amount",
    "type": "Integer",
    "variableType": "integer",
    "value": 5,
    "processInstanceId": "aProcessInstanceId",
    "executionId": "b68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726",
    "caseExecutionId": null,
    "caseInstanceId": null,
    "serializationConfig": null
  },
  {
    "id": "someOtherId",
    "name": "amount",
    "type": "Integer",
    "variableType": "integer",
    "value": 15,
    "processInstanceId": "aProcessInstanceId",
    "executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726",
    "caseExecutionId": null,
    "caseInstanceId": null,
    "serializationConfig": null
  },
  {
    "id": "yetAnotherId",
    "name": "amount",
    "type": "Integer",
    "variableType": "integer",
    "value": 150,
    "processInstanceId": "anotherProcessInstanceId",
    "executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
    "taskId": null,
    "activityInstanceId": "Task_2:b68b71ca-e310-11e2-beb0-f0def1557726",
    "caseExecutionId": null,
    "caseInstanceId": null,
    "serializationConfig": null
  }      
]

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 belong to one of the passed and comma-separated process instance ids.
executionIdIn Only include variable instances which belong to one of the passed and comma-separated execution ids.
caseInstanceIdIn Only include variable instances which belong to one of the passed case instance ids.
caseExecutionIdIn Only include variable instances which belong to one of the passed case execution ids.
taskIdIn Only include variable instances which belong to one of the passed and comma-separated task ids.
activityInstanceIdIn Only include variable instances which belong 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, operator 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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 filtering 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.
deserializeValues

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default true).

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

Note:While true is the default value for reasons of backward compatibility, we recommend setting this parameter to false when developing web applications that are independent of the Java process applications deployed to the engine.

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 belong to one of the passed process instance ids.
executionIdIn Only include variable instances which belong to one of the passed execution ids.
caseInstanceIdIn Only include variable instances which belong to one of the passed case instance ids.
caseExecutionIdIn Only include variable instances which belong to one of the passed case execution ids.
taskIdIn Only include variable instances which belong to one of the passed task ids.
activityInstanceIdIn Only include variable instances which belong 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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
id String The id of the variable instance.
name String The name of the variable instance.
type String The value type of the variable.
value String/Number/Boolean/Object The variable's value. Value differs depending on the variable's type and on the deserializeValues parameter.
valueInfo Object

A JSON object containing additional, value-type-dependent properties.

For variables of type Object, the following properties are returned:

  • objectTypeName: A string representation of the object's type name.
  • serializationDataFormat: The serialization format used to store the variable.
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.
caseInstanceId String The id of the case instance that this variable instance belongs to.
caseExecutionId String The id of the case 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

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

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 therefore it is 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 belong to one of the passed process instance ids.
executionIdIn Only include variable instances which belong to one of the passed execution ids.
caseInstanceIdIn Only include variable instances which belong to one of the passed case instance ids.
caseExecutionIdIn Only include variable instances which belong to one of the passed case execution ids.
taskIdIn Only include variable instances which belong to one of the passed task ids.
activityInstanceIdIn Only include variable instances which belong 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 - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; 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}