REST API

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

Structure

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

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

Engine Usage

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

You may prepend /engine/{name} to any of the methods (unless otherwise documented) to access another engine 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.

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.

The REST API uses the default date format yyyy-MM-dd'T'HH:mm:ss which represents a date without milliseconds and timezone information, eg 2016-01-25T13:33:42. A custom date format can be configured in the web.xml file of the REST API. Therefore the ServletContextListener CustomJacksonDateFormatListener has to be added. And the custom date format can be specified by the context parameter org.camunda.bpm.engine.rest.jackson.dateFormat.

For example if the date format should contain milliseconds and timezone information (yyyy-MM-dd'T'HH:mm:ss.SSSZ) the following configuration can be used:

<?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.CustomJacksonDateFormatListener
    </listener-class>
  </listener>

  <context-param>
    <param-name>org.camunda.bpm.engine.rest.jackson.dateFormat</param-name>
    <param-value>yyyy-MM-dd'T'HH:mm:ss.SSSZ</param-value>
  </context-param>

  <!-- ... -->
</web-app>

With this configuration the REST API will return dates with millisecond precision and timezone information. Also new dates can be submitted with milliseconds and timezone information to the REST API without losing these details.

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.

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 com.fasterxml.jackson.jaxrs:jackson-jaxrs-json-provider artifact (as well as transitive Jackson dependencies) 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: com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider, org.camunda.bpm.engine.rest.exception.JsonMappingExceptionHandler and org.camunda.bpm.engine.rest.exception.JsonParseExceptionHandler. 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.

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:

DefaultHalResourceCache Configuration Options

The simple default cache implementation DefaultHalResourceCache provides following configuration options:

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

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.

Deletes an authorization by id.

Method

DELETE /authorization/{id}

Parameters

Path Parameters

Result

This method returns no content.

Response codes

Example

Request

DELETE /authorization/anAuthorizationId

Response

Status 204. No content.

Retrieves a single authorization by Id.

Method

GET /authorization/{id}

Parameters

Path Parameters

Result

A JSON array with the following properties:

Response codes

Example

Request

GET /authorization/anAuthorizationId

Response

Status 200.

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

Performs an authorization check for the currently authenticated user.

Method

GET /authorization/check

Parameters

Query Parameters

Result

A JSON array with the following properties:

Response codes

Example

Request

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

Response

Status 200.

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

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

Method

GET /authorization

Parameters

Query Parameters

Result

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

Response codes

Example

Request

GET /authorization?userIdIn=jonny1,jonny2

Response

Status 200.

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

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

Method

GET /authorization/count

Parameters

Query Parameters

Result

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

Response codes

Example

Request

GET /authorization/count?userIdIn=jonny1,jonny2

Response

Status 200.

{"count": 2}

The /authorization resource supports two custom OPTIONS requests, one for the resource as such and one for individual authorization instances. The OPTIONS request allows 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

Response codes

Example

Request

OPTIONS /authorization/anAuthorizationId

Response

Status 200.

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

Creates a new authorization

Method

POST /authorization/create

Parameters

Request Body

A JSON object with the following properties:

Result

A json array with the following properties:

Response codes

Example

Request

POST /authorization/create

Request body:

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

Response

Status 200.

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

Updates a single authorization.

Method

PUT /authorization/{id}

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

PUT /authorization/anAuthorizationId

Request body:

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

Response

Status 204. No content.

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

Result

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

Response codes

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

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

Result

The image diagram of this case.

Response codes

Example

Request

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

GET /case-definition/key/invoice/diagram

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

Result

A JSON array of case definition objects. Each case definition object has the following properties:

Response codes

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

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

Result

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

Response codes

Example

Request

GET /case-definition/count?keyLike=Key&version=2

Response

{
  "count": 1
}

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

Result

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

Response codes

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

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

Request Body

A JSON object with the following properties:

Result

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

Response codes

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
}

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

Result

This method returns no content.

Response codes

Example

Request

DELETE /case-execution/aCaseExecutionId/localVariables/aVarName

Response

Status 204. No content.

Deletes a variable of a given case execution.

Method

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

Parameters

Path Parameters

Result

This method returns no content.

Response codes

Example

Request

DELETE /case-execution/aCaseExecutionId/variables/aVarName

Response

Status 204. No content.

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

Method

GET /case-execution/{id}

Parameters

Path Parameters

Result

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

Response codes

Example

Request

GET /case-execution/aCaseExecutionId

Response

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

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

Query Parameters

Result

A JSON object with the following properties:

Response codes

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

Retrieves all variables of a given case execution.

Method

GET /case-execution/{id}/localVariables

Parameters

Path Parameters

Query Parameters

Result

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

Response codes

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

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

Result

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

Response codes

Example

Request

GET /case-execution?variables=myVariable_eq_camunda,mySecondVariable_neq_aBadValue

Response

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

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

Result

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

Response codes

Example

Request

GET /case-execution/count?variables=myVariable_eq_camunda

Response

{
  "count": 1
}

Retrieves a variable of a given case execution.

Method

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

Parameters

Path Parameters

Query Parameters

Result

A JSON object with the following properties:

Response codes

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

Retrieves all variables of a given case execution.

Method

GET /case-execution/{id}/variables

Parameters

Path Parameters

Query Parameters

Result

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

Response codes

Example

Request

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

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

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

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

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

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

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

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

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

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

Request Body

A JSON object with the following properties:

Result

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

Response codes

Example

Request

POST /case-execution

Request body:

{
  "variables":
    [
      {
        "name" : "myVariable",
        "operator" : "eq",
        "value" : "camunda"
      },
      {
        "name" : "mySecondVariable",
        "operator" : "neq",
        "value" : 124
      }
    ],
  "caseDefinitionId" : "aCaseDefinitionId",
  "sorting":
    [
      {
        "sortBy": "caseDefinitionKey",
        "sortOrder": "asc"
      },
      {
        "sortBy": "caseExecutionId",
        "sortOrder": "asc"
      }
    ]
}

Response

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

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:

Result

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

Response codes

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
}

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

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

Sets the serialized value for a binary variable.

Method

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

Parameters

Path Parameters

Request Body

A multipart form submit with the following parts:

Result

This method returns no content.

Response codes

Example

Request

(1) Post 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--

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

Method

POST /case-execution/{id}/variables

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /case-execution/aCaseExecutionId/variables

Request body:

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

Response

Status 204. No content.

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

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

Sets the serialized value for a binary variable.

Method

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

Parameters

Path Parameters

Request Body

A multipart form submit with the following parts:

Result

This method returns no content.

Response codes

Example

Request

(1) Post 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--

Sets a variable of a given case execution.

Method

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

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

Deletes a variable of a given case instance.

Method

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

Parameters

Path Parameters

Result

This method returns no content.

Response codes

Example

Request

DELETE /case-instance/aCaseInstanceId/variables/aVarName

Response

Status 204. No content.

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

Method

GET /case-instance/{id}

Parameters

Path Parameters

Result

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

Response codes

Example

Request

GET /case-instance/aCaseInstanceId

Response

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

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

Result

A JSON array of case instance objects. Each case instance object has the following properties:

Response codes

Example

Request

GET /case-instance?variables=myVariable_eq_camunda,mySecondVariable_neq_aBadValue

Response

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

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

Result

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

Response codes

Example

Request

GET /case-instance/count?variables=myVariable_eq_camunda

Response

{
  "count": 1
}

Retrieves a variable of a given case instance.

Method

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

Parameters

Path Parameters

Query Parameters

Result

A JSON object with the following properties:

Response codes

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

Retrieves all variables of a given case instance.

Method

GET /case-instance/{id}/variables

Parameters

Path Parameters

Query Parameters

Result

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

Response codes

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

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

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

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

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

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

Request Body

A JSON object with the following properties:

Result

A JSON array of case instance objects. Each case instance object has the following properties:

Response codes

Example

Request

POST /case-instance

Request body:

{
  "variables":
    [
      {
        "name" : "myVariable",
        "operator" : "eq",
        "value" : "camunda"
      },
      {
        "name" : "mySecondVariable",
        "operator" : "neq",
        "value" : 124
      }
    ],
  "caseDefinitionId" : "acaseDefinitionId",
  "sorting":
    [
      {
        "sortBy": "caseDefinitionKey",
        "sortOrder": "asc"
      },
      {
        "sortBy": "caseInstanceId",
        "sortOrder": "asc"
      }
    ]
}

Response

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

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:

Result

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

Response codes

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
}

Sets the serialized value for a binary variable.

Method

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

Parameters

Path Parameters

Request Body

A multipart form submit with the following parts:

Result

This method returns no content.

Response codes

Example

Request

(1) Post 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--

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

Method

POST /case-instance/{id}/variables

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /case-instance/aCaseInstanceId/variables

Request body:

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

Response

Status 204. No content.

Sets a variable of a given case instance.

Method

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

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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.

Deletes a deployment.

Method

DELETE /deployment/{id}

Parameters

Path Parameters

Query Parameters

Result

This method returns no content.

Response codes

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.

Retrieves a single deployment by id.

Method

GET /deployment/{id}

Parameters

Path Parameters

Result

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

Response codes

Example

Request

GET /deployments/someDeploymentId

Response

Status 200.

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

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

Result

A JSON array of deployment objects. Each deployment object has the following properties:

Response codes

Example

Request

GET /deployment?name=deploymentName

Response

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

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

Result

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

Response codes

Example

Request

GET /deployment/count?name=deploymentName

Response

{"count": 1}

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

Method

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

Parameters

Path Parameters

Result

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

Response codes

Example

Request

GET /deployments/someDeploymentId/resources/someResourceId

Response

Status 200.

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

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

Method

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

Parameters

Path Parameters

Result

Byte Stream.

Response codes

Example

Request

GET /deployments/someDeploymentId/resources/someResourceId/data

Response

Status 200.

Byte Stream.

Retrieves all deployment resources of a given deployment.

Method

GET /deployment/{id}/resources

Parameters

Path Parameters

Result

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

Response codes

Example

Request

GET /deployment/anDeploymentId/resources

Response

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

Create a deployment.

Method

POST /deployment/create

Parameters

Request Body

A multipart form submit with the following parts:

Result

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

Response codes

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

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

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

Method

GET /engine

Parameters

This method takes no parameters.

Result

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

Response codes

Example

Request

GET /engine

Response

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

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

Method

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

Parameters

Path Parameters

Result

This method returns no content.

Response codes

Example

Request

DELETE /execution/anExecutionId/localVariables/aVarName

Response

Status 204. No content.

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

Method

GET /execution/{id}

Parameters

Path Parameters

Result

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

Response codes

Example

Request

GET /execution/anExecutionId

Response

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

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

Method

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

Parameters

Path Parameters

Query Parameters

Result

A JSON object with the following properties:

Response codes

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

Retrieves all variables of a given execution.

Method

GET /execution/{id}/localVariables

Parameters

Path Parameters

Query Parameters

Result

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

Response codes

Example 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 a message event subscription for a specific execution and a message name.

Method

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

Parameters

Path Parameters

Result

A JSON object with the following properties:

Response codes

Example

Request

GET /execution/anExecutionId/messageSubscriptions/someMessage

Response

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

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

Method

GET /execution

Parameters

Query Parameters

Result

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

Response codes

Example

Request

GET /execution?variables=myVariable_eq_camunda

Response

Status 200.

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

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

Method

GET /execution/count

Parameters

Query Parameters

Result

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

Response codes

Example

Request

GET /execution/count?variables=myVariable_eq_camunda

Response

{"count": 1}

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

Method

POST /execution/{id}/localVariables

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /execution/anExecutionId/localVariables

Request body:

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

Response

Status 204. No content.

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

Method

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

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /execution/anExecutionId/messageSubscriptions/someMessage/trigger

Request body:

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

Response

Status 204. No content.

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

Method

POST /execution

Parameters

Query Parameters

Request Body

A JSON object with the following properties:

Result

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

Response codes

Example

Request

POST /execution

Request body:

{"variables":
    [{"name": "myVariable",
     "operator": "eq",
     "value": "camunda"
    },
    {"name": "mySecondVariable",
     "operator": "neq",
     "value": 124}],
"processDefinitionId":"aProcessDefinitionId",
"sorting":
    [{"sortBy": "definitionKey",
    "sortOrder": "asc"
    },
    {"sortBy": "instanceId",
    "sortOrder": "desc"
    }]
}

Response

Status 200.

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

Query for the number of executions that fulfill given parameters. This method takes the same message body as the POST query and 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:

Result

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

Response codes

Example

Request

POST /execution/count

Request body:

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

Response

{"count": 1}

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

Method

POST /execution/{id}/signal

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

Example

Request

POST /execution/{id}/signal

Request body:

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

Response

Status 204. No content.

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

Method

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

Parameters

Path Parameters

Request Body

A JSON object with the following properties:

Result

This method returns no content.

Response codes

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

Sets the value for a binary variable.

Method

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

Parameters

Path Parameters

Request Body

A multipart form submit with the following parts:

Result

This method returns no content.

Response codes

Example

Request

(1) Post 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--

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

Result

A JSON array of filter objects. Each filter object has the following properties:

Response codes

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