The goal of the REST API is to provide access to all relevant interfaces of the engine.
These documents explain all existing methods in the REST API. For each method they provide:
The methods as described work on the default process engine as given by the available ProcessEngineProvider
service.
You may prepend /engine/{name}
to any of the methods (unless otherwise documented) to access another engine. name
is the name of the process engine as returned by ProcessEngine#getName()
.
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"}
.
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"}
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.
The authentication filter works fine whenever the JAX-RS application containing the REST API is deployed as a servlet. This is not neccessarily the case. One such case we are aware of is with some types of Resteasy deployments:
Resteasy allows to deploy a JAX-RS application as a servlet filter (see the Resteasy docs). If you choose this method to deploy the REST API application, which we also do in the Tomcat distro, the authentication filter requires an extra init-param named rest-url-pattern-prefix
. The value has to correspond to the servlet path (see HttpServletRequest#getServletPath()) as in the case that the JAX-RS application are deployed as a servlet.
Example: If the Resteasy configuration is
<filter>
<filter-name>Resteasy</filter-name>
<filter-class>
org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
</filter-class>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>org.camunda.bpm.engine.rest.impl.application.DefaultApplication</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>Resteasy</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
the following init-param has to be set:
<init-param>
<param-name>rest-url-pattern-prefix</param-name>
<param-value></param-value>
</init-param>
In the example above the value is empty, because the Resteasy filter mapping is /\*
and a servlet with that mapping would have an empty servlet path. Similarly, the filter mapping url /rest/\*
maps to the init-param /rest
and so on.
The REST API is included in camunda's pre-built distributions.
It may be accessed via the context /engine-rest
and uses the engines provided by the class BpmPlatform
.
The default process engine is available out of the box by accessing /engine-rest/engine/default/{rest-methods}
or simply /engine-rest/{rest-methods}
. Any other shared process engine, i.e. it is globally visible, that is created later is available through /engine-rest/engine/{name}/{rest-methods}
without any further configuration.
Authentication is deactivated by default, but can be activated as described in the authentication section.
The REST API is an artifact of its own, which means that it can be embedded in any other JAX-RS application independently of the engine.
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.
Add the REST API as a Maven dependency to your project.
<dependency>
<groupId>org.camunda.bpm</groupId>
<artifactId>camunda-engine-rest</artifactId>
<classifier>classes</classifier>
<version>7.0.0-Final</version>
</dependency>
Add those REST resources to your JAX-RS application that you need. Example:
@ApplicationPath("/")
public class MyApplication extends Application {
@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> classes = new HashSet<Class<?>>();
// add your own classes
...
// add camunda engine rest classes that you need
classes.add(org.camunda.bpm.engine.rest.impl.ProcessEngineRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.ProcessDefinitionRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.ProcessInstanceRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.TaskRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.IdentityRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.MessageRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.JobRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.ExecutionRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.VariableInstanceRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.UserRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.GroupRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.AuthorizationRestServiceImpl.class);
classes.add(org.camunda.bpm.engine.rest.impl.history.HistoryRestServiceImpl.class);
// mandatory
classes.add(org.camunda.bpm.engine.rest.mapper.JacksonConfigurator.class);
classes.add(org.camunda.bpm.engine.rest.exception.RestExceptionHandler.class);
classes.add(org.camunda.bpm.engine.rest.exception.ProcessEngineExceptionHandler.class);
return classes;
}
}
The classes org.camunda.bpm.engine.rest.*RestServiceImpl
classes contain the methods as structured in this documentation.
ProcessEngineRestServiceImpl
adds the functionality that different engines may be addressed.
If it is not included the default engine will always be used and /engine/{name}
URLs will not be available.
JacksonConfigurator
is required to configure the serialization of date fields correctly.
You may also have to add the following Jackson providers: org.codehaus.jackson.jaxrs.JacksonJsonProvider
,
org.codehaus.jackson.jaxrs.JsonMappingExceptionMapper
and org.codehaus.jackson.jaxrs.JsonParseExceptionMapper
.
Depending on the runtime environment, this may not be necessary.
On JBoss AS 7 these should be automatically added as an implicit module dependency.
For proper exception responses of the format as described in the Introduction,
it is required to include RestExceptionHandler
. ProcessEngineExceptionHandler
is used to translate any exception thrown by the
engine that is not explicitly handled by the REST API classes to a generic HTTP 500 error with the same response body format.
If you would like to have all kinds of exceptions translated to this format, you can use org.camunda.bpm.engine.rest.exception.ExceptionHandler
instead of ProcessEngineExceptionHandler
.
Next is the wiring of the REST API and the process engine(s).
This requires to create a Service Provider that implements the interface ProcessEngineProvider
and declare it in a file META-INF/services/org.camunda.bpm.engine.rest.spi.ProcessEngineProvider
.
You may also declare the class org.camunda.bpm.engine.rest.impl.application.ContainerManagedProcessEngineProvider
which comes with the REST API and uses the methods the class org.camunda.bpm.BpmPlatform
provides.
Retrieves the names of all process engines available on your platform.
Note: You cannot prepend /engine/{name}
to this method.
GET /engine
This method takes no parameters.
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. |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
GET /engine
[{"name":"default"},
{"name":"anotherEngineName"}]
Deletes a variable in the context of a given execution. Deletion does not propagate upwards in the execution hierarchy.
DELETE /execution/{id}/localVariables/{varId}
Name | Description |
---|---|
id | The id of the execution to delete the variable from. |
varId | The name of the variable to delete. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. |
DELETE /execution/anExecutionId/localVariables/aVarName
Status 204. No content.
Retrieves a single execution according to the Execution
interface in the engine.
GET /execution/{id}
Name | Description |
---|---|
id | The id of the execution to be retrieved. |
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. |
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. |
GET /execution/anExecutionId
{"id":"anExecutionId",
"processInstanceId":"aProcInstId",
"ended":false}
Retrieves a variable from the context of a given execution. Does not traverse the parent execution hierarchy.
GET /execution/{id}/localVariables/{varId}
Name | Description |
---|---|
id | The id of the execution to retrieve the variable for. |
varId | The name of the variable to get. |
A json object with the following properties:
Name | Value | Description |
---|---|---|
value | String/Number/Boolean/Object | Object serialization uses Jackson's POJO/bean property introspection feature. |
type | String | The simple class name of the variable object. |
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. |
GET /execution/anExecutionId/localVariables/aVarName
{"value" : "someValue",
"type" : "String"}
Retrieves all variables of a given execution.
GET /execution/{id}/localVariables
Name | Description |
---|---|
id | The id of the execution to retrieve the variables for. |
A json object of variables key-value pairs. Each key is a variable name and each value a variable value object that has the following properties:
Name | Value | Description |
---|---|---|
value | String/Number/Boolean/Object | Object serialization uses Jackson's POJO/bean property introspection feature. |
type | String | The simple class name of the variable object. |
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. |
GET /execution/anExecutionId/localVariables
{"anExecutionVariableKey":
{"value":
{"property1":"aPropertyValue",
"property2":true},
"type":"ExampleVariableObject"}}
Get a message event subscription for a specific execution and a message name.
GET /execution/{id}/messageSubscriptions/{messageName}
Name | Description |
---|---|
id | The id of the execution that holds the subscription. |
messageName | The name of the message that the subscription corresponds to. |
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 . |
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. |
GET /execution/anExecutionId/messageSubscriptions/someMessage
{"id": "anEventSubscriptionId",
"eventType": "message",
"eventName": "anEvent",
"executionId": "anExecutionId",
"processInstanceId": "aProcInstId",
"activityId": "anActivity",
"createdDate": "2013-01-23T13:59:43"}
Query for the number of executions that fulfill given parameters. Parameters may be static as well as dynamic runtime properties of executions. The size of the result set can be retrieved by using the get executions count method.
GET /execution
Name | Description |
---|---|
businessKey | Filter by the business key of the process instances the executions belong to. |
processDefinitionId | Filter by the process definition the executions run on. |
processDefinitionKey | Filter by the key of the process definition the executions run on. |
processInstanceId | Filter by the id of the process instance the execution belongs to. |
activityId | Filter by the id of the activity the execution currently executes. |
signalEventSubscriptionName | Select only those executions that expect a signal of the given name. |
messageEventSubscriptionName | Select only those executions that expect a message of the given name. |
active | Only include active executions. Values may be true or false . |
suspended | Only include suspended executions. Values may be true or false . |
variables | Only include executions that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
processVariables | Only include executions that belong to a process instance with variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals.key and value may not contain underscore or comma characters.
|
sortBy | Sort the results lexicographically by a given criterion. Valid values are
instanceId , definitionKey and definitionId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
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. |
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. |
GET /execution?variables=myVariable_eq_camunda
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.
GET /execution/count
Name | Description |
---|---|
businessKey | Filter by the business key of the process instances the executions belong to. |
processDefinitionId | Filter by the process definition the executions run on. |
processDefinitionKey | Filter by the key of the process definition the executions run on. |
processInstanceId | Filter by the id of the process instance the execution belongs to. |
activityId | Filter by the id of the activity the execution currently executes. |
signalEventSubscriptionName | Select only those executions that expect a signal of the given name. |
messageEventSubscriptionName | Select only those executions that expect a message of the given name. |
active | Only include active executions. Values may be true or false . |
suspended | Only include suspended executions. Values may be true or false . |
variables | Only include executions that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
processVariables | Only include executions that belong to a process instance with variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals.key and value may not contain underscore or comma characters.
|
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching executions. |
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. |
GET /execution/count?variables=myVariable_eq_camunda
{"count": 1}
Updates or deletes the variables in the context of an execution. The updates do not propagate upwards in the execution hierarchy. Updates precede deletes. So if a variable is updated AND deleted, the deletion overrides the update.
POST /execution/{id}/localVariables
Name | Description |
---|---|
id | The id of the execution to set variables for. |
A json object with the following properties:
Name | Description |
---|---|
modifications | A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object.
A variable value object has has the property value , which is the value to update, and type , which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. |
deletions | An array of String keys of variables to be deleted. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | application/json | Request successful. |
400 | application/json | The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
500 | application/json | Update or delete could not be executed, for example because the execution does not exist. |
POST /execution/anExecutionId/localVariables
Request body:
{"modifications":
{"aVariable": {"value": "aValue", "type": "String"},
"anotherVariable": {"value": 42, "type": "Integer"}},
"deletions": [
"aThirdVariable", "FourthVariable"
]}
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.
POST /execution/{id}/messageSubscriptions/{messageName}/trigger
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. |
A json object with the following properties:
Name | Description |
---|---|
messageName | The name of the message to deliver. |
variables | A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object.
A variable value object has has the property value , which is the value to update, and type , which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. | |
400 | application/json | The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
500 | application/json | The addressed execution has no pending message subscriptions for the given message. See the Introduction for the error response format. |
POST /execution/anExecutionId/messageSubscriptions/someMessage/trigger
Request body:
{"messageName" : "aMessage",
"variables" :
{"aVariableName" : {"value" : true, "type": "Boolean"},
"anotherVariableName" : {"value" : 42, "type": "Integer"}}
}
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'.
POST /execution
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. |
A json object with the following properties:
Name | Description |
---|---|
businessKey | Filter by the business key of the process instances the executions belong to. |
processDefinitionId | Filter by the process definition the executions run on. |
processDefinitionKey | Filter by the key of the process definition the executions run on. |
processInstanceId | Filter by the id of the process instance the execution belongs to. |
activityId | Filter by the id of the activity the execution currently executes. |
signalEventSubscriptionName | Select only those executions that expect a signal of the given name. |
messageEventSubscriptionName | Select only those executions that expect a message of the given name. |
active | Only include active executions. Values may be true or false . |
suspended | Only include suspended executions. Values may be true or false . |
variables | A json array to only include executions that have variables with certain values. The array consists of objects with the three properties key , operator and value .
key (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.value may be String , Number or Boolean .
Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore characters.
|
processVariables | A json array to only include executions that belong to a process instance with variables with certain values. A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals.key and value may not contain underscore characters.
|
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. |
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. |
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. |
POST /execution
Request body:
{"variables":
[{"name": "myVariable",
"operator": "eq",
"value": "camunda"
},
{"name": "mySecondVariable",
"operator": "neq",
"value": 124}],
"processDefinitionId":"aProcessDefinitionId"}
Status 200.
[{"id":"anId",
"processInstanceId":"aProcInstId",
"ended":false}]
Query for the number of executions that fulfill given parameters. This method takes the same message body as the POST query and is thus slightly more powerful than the GET query count api.
POST /process-instance/count
A json object with the following properties:
Name | Description |
---|---|
businessKey | Filter by the business key of the process instances the executions belong to. |
processDefinitionId | Filter by the process definition the executions run on. |
processDefinitionKey | Filter by the key of the process definition the executions run on. |
processInstanceId | Filter by the id of the process instance the execution belongs to. |
activityId | Filter by the id of the activity the execution currently executes. |
signalEventSubscriptionName | Select only those executions that expect a signal of the given name. |
messageEventSubscriptionName | Select only those executions that expect a message of the given name. |
active | Only include active executions. Values may betrue or false . |
suspended | Only include suspended executions. Values may be true or false . |
variables | A json array to only include executions that have variables with certain values. The array consists of objects with the three properties key , operator and value .
key (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.value may be String , Number or Boolean .
Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore characters.
|
processVariables | A json array to only include executions that belong to a process instance with variables with certain values. A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals.key and value may not contain underscore characters.
|
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching executions. |
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. |
POST /execution/count
Request body:
{"variables":
[{"name": "myVariable",
"operator": "eq",
"value": "camunda"
},
{"name": "mySecondVariable",
"operator": "neq",
"value": 124}],
"processDefinitionId":"aProcessDefinitionId"}
{"count": 1}
Signals a single execution. Can for example be used to explicitly skip user tasks or signal asynchronous continuations.
POST /execution/{id}/signal
Name | Description |
---|---|
id | The id of the execution to signal. |
A json object with the following properties:
Name | Description |
---|---|
variables | A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object.
A variable value object has has the propertyvalue , which is the value to update, andtype , which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | application/json | Request successful. |
400 | application/json | The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
POST /execution/{id}/signal
Request body:
{"variables":
{"myVariable": {"value": "camunda", "type": "String"},
"mySecondVariable": {"value": 124, "type": "Integer"}}
}
Status 204. No content.
Sets a variable in the context of a given execution. Update does not propagate upwards in the execution hierarchy.
PUT /execution/{id}/localVariables/{varId}
Name | Description |
---|---|
id | The id of the execution to set the variable for. |
varId | The name of the variable to set. |
A json object with the following properties:
Name | Description |
---|---|
value | The value of the variable to set. |
type | The type of the variable to set. Valid types are Integer, Short, Long, Double, String, Boolean and Date. |
This method returns no content.
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. |
PUT /execution/anExecutionId/localVariables/aVarName
{"value" : "someValue", "type": "String"}
Status 204. No content.
Deletes a group by id.
DELETE /group/{id}
Name | Description |
---|---|
id | The id of the group to be deleted. |
Empty.
This method returns no content.
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
404 | application/json | Group cannot be found. See the Introduction for the error response format. |
DELETE /group/sales
Status 204. No content.
Retrieves a single group.
GET /group/{id}
Name | Description |
---|---|
id | The id of the group to be retrieved. |
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. |
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. |
GET /group/sales
Status 200.
{"id":"sales",
"name":"Sales",
"type":"Organizational Unit"}
Query for a list of groups using a list of parameters. The size of the result set can be retrieved by using the get groups count method.
GET /group
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. |
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. |
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. |
GET /group?name=Sales
Status 200.
[{"id":"sales",
"name":"Sales",
"type":"Organizational Unit"}]
Query for groups using a list of parameters and retrieves the count.
GET /group/count
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. |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching groups. |
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. |
GET /group/count?name=Sales
Status 200.
{"count": 1}
Removes a memeber from a group.
DELETE /group/{id}/members/{userId}
Name | Description |
---|---|
id | The id of the group |
userId | The id of user to remove from the group |
Empty.
This method returns no content.
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
500 | application/json | In case an error occurs. See the Introduction for the error response format. |
DELETE /group/sales/members/jonny1
Status 204. No content.
Add a member to a group.
PUT /group/{id}/members/{userId}
None.
None.
Code | Media type | Description |
---|---|---|
204 | Empty | Request successful. |
500 | application/json | In case an internal error occurs. See the Introduction for the error response format. |
PUT /group/sales/members/jonny1
Request body:
Empty.
None.
The /group
resource supports two custom OPTIONS requests, one for the resource as such and one for individual group instances. The options request allows checking for the set of available operations that the currently authenticated user can perform on the /group
resource. The fact whether the user can perform an operation may depend on various things, including the users authorizations to interact with this resource and the interal configuration of the process engine.
OPTIONS /group
for available interactions on resource
OPTIONS /group/{id}
for available interactions on resource instance
A Json object with a single property named links
, providing a list of resource links. Each link has the following properties
Name | Value | Description |
---|---|---|
method | String | The HTTP method to use for the interaction. |
href | String | The interaction URL |
rel | String | The relation of the interaction (i.e., a symbolic name representing the nature of the interaction). Examples: create , delete ... |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
OPTIONS /group
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"}]}
OPTIONS /group/aGroupId
Status 200.
{"links":[
{"method":"GET","href":"http://localhost:8080/camunda/api/engine/engine/default/group/aGroupId","rel":"self"},
{"method":"DELETE","href":"http://localhost:8080/camunda/api/engine/engine/default/group/aGroupId","rel":"delete"},
{"method":"PUT","href":"http://localhost:8080/camunda/api/engine/engine/default/group/aGroupId","rel":"update"}]}
Create a new group.
POST /group/create
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. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. | |
500 | application/json | The group could not be created due to an internal server error. See the Introduction for the error response format. |
POST /group/create
Request body:
{"id":"sales",
"name":"Sales",
"type":"Organizational Unit"}
Status 204. No content.
Updates a given group.
PUT /group/{id}
Name | Type | Description |
---|---|---|
id | String | The id of the group. |
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. |
Empty.
Code | Media type | Description |
---|---|---|
204 | Empty. | Request successful. |
404 | application/json | If the group with the requested Id cannot be found. |
500 | application/json | The group could not be updated due to an internal server error. See the Introduction for the error response format. |
PUT /group/sales
Request body:
{"id":"sales",
"name":"Sales",
"type":"Organizational Unit"}
Empty.
Query for historic activity instances that fulfill the given parameters. The size of the result set can be retrieved by using the count method.
GET /history/activity-instance
Name | Description |
---|---|
activityInstanceId | Filter by activity instance id. |
processInstanceId | Filter by process instance id. |
processDefinitionId | Filter by process definition id. |
executionId | Filter by the id of the execution that executed the activity instance. |
activityId | Filter by the activity id (according to BPMN 2.0 XML). |
activityName | Filter by the activity name (according to BPMN 2.0 XML). |
activityType | Filter by activity type. |
taskAssignee | Only include activity instances that are user tasks and assigned to a given user. |
finished | Only include finished activity instances. Values may be true or false . |
unfinished | Only include unfinished activity instances. Values may be true or false . |
sortBy | Sort the results by a given criterion. Valid values are
activityInstanceID , instanceId , executionId , activityId , activityName , activityType , startTime , endTime , duration , definitionId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
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). |
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. |
GET /history/activity-instance?activityType=userTask&taskAssignee=peter
[{"id": "aHistoricActivityInstanceId",
"parentActivityInstanceId": "aHistoricParentActivityInstanceId",
"activityId": "anActivity",
"activityName": "anActivityName",
"activityType": "userTask",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anExecutionId",
"taskId": "aTaskId",
"calledProcessInstanceId": "aHistoricCalledProcessInstanceId",
"assignee": "peter",
"startTime": "2013-04-23T11:20:43",
"endTime": "2013-04-23T18:42:43",
"durationInMillis": 2000}]
Query for the number of historic activity instances that fulfill the given parameters. Takes the same parameters as the get historic activity instances method.
GET /history/activity-instance/count
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 . |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching historic activity instances. |
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. |
GET /history/activity-instance/count?activityType=userTask
{"count": 1}
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.
GET /history/process-instance
Name | Description |
---|---|
processInstanceIds | Filter by process instance ids. Must be a comma-separated list of process instance ids. |
processInstanceBusinessKey | Filter by process instance business key. |
superProcessInstanceId | Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id. |
processDefinitionId | Filter by the process definition the instances run on. |
processDefinitionKey | Filter by the key of the process definition the instances run on. |
processDefinitionKeyNotIn | Exclude instances that belong to a set of process definitions. Must be a comma-separated list of process definition keys. |
finished | Only include finished process instances. Values may be true or false . |
unfinished | Only include unfinished process instances. Values may be true or false . |
startedBy | Only include process instances that were started by the given user. |
startedBefore | Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
startedAfter | Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
finishedBefore | Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
finishedAfter | Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
variables | Only include process instances that have/had variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
sortBy | Sort the results by a given criterion. Valid values are
instanceId , definitionId , businessKey , startTime , endTime , duration .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
A json array of historic process instance objects. Each historic process instance object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The id of the process instance. |
superProcessInstanceId | String | The id of the parent process instance if exists. |
processDefinitionId | String | The id of the process definition that this process instance belongs to. |
businessKey | String | The business key of the process instance. |
startTime | String | The time the instance was started. Has the format yyyy-MM-dd'T'HH:mm:ss . |
endTime | String | The time the instance ended. Has the format yyyy-MM-dd'T'HH:mm:ss . |
durationInMillis | Number | The time the instance took to finish (in milliseconds). |
startUserId | String | The id of the user who started the process instance. |
startActivityId | String | The id of the initial activity that was executed (e.g. a start event). |
deleteReason | String | The provided delete reason in case the process instance was cancelled during execution. |
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. |
GET /history/process-instance?finishedAfter=2013-01-01T00:00:00&finishedBefore=2013-04-01T23:59:59
[{"id": "aProcInstId",
"businessKey": "aKey",
"processDefinitionId": "aProcDefId",
"startTime": "2013-03-23T13:42:43",
"endTime": "2013-03-23T13:42:45",
"durationInMillis": 2000,
"startUserId": "aStartUserId",
"startActivityId": "aStartActivityId",
"deleteReason": "aDeleteReason",
"superProcessInstanceId": "aSuperProcessInstanceId"}]
Query for the number of historic process instances that fulfill the given parameters. Takes the same parameters as the Get Activity Instances method.
GET /history/process-instance/count
Name | Description |
---|---|
processInstanceIds | Filter by process instance ids. Must be a comma-separated list of process instance ids. |
processInstanceBusinessKey | Filter by process instance business key. |
superProcessInstanceId | Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id. |
processDefinitionId | Filter by the process definition the instances run on. |
processDefinitionKey | Filter by the key of the process definition the instances run on. |
processDefinitionKeyNotIn | Exclude instances that belong to a set of process definitions. Must be a comma-separated list of process definition keys. |
finished | Only include finished process instances. Values may be true or false . |
unfinished | Only include unfinished process instances. Values may be true or false . |
startedBy | Only include process instances that were started by the given user. |
startedBefore | Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
startedAfter | Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
finishedBefore | Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
finishedAfter | Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
variables | Only include process instances that have/had variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching historic process instances. |
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. |
GET /history/process-instance/count?variables=myVariable_eq_camunda
{"count": 1}
Query for historic variable instances that fulfill the given parameters. The size of the result set can be retrieved by using the count method.
GET /history/variable-instance
Name | Description |
---|---|
variableName | Filter by variable name. |
variableNameLike | Restrict to variables with a name like the parameter. |
variableValue | Filter by variable value. Is treated as a String object on server side. |
processInstanceId | Filter by the process instance the variable belongs to. |
sortBy | Sort the results by a given criterion. Valid values are instanceId , variableName .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
A json array of historic variable instance objects. Each historic activity instance object has the following properties:
Name | Value | Description |
---|---|---|
name | String | The name of the variable instance. |
type | String | The type of the variable instance. |
value | String | The value of the variable instance. |
processInstanceId | String | The id the process instance belongs to. |
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. |
GET /history/variable-instance?variableName=my_variable
[{"name": "my_variable",
"type": "String",
"value": "my_value",
"processInstanceId": "aVariableInstanceProcInstId"}]
Query for the number of historic variable instances that fulfill the given parameters. Takes the same parameters as the get historic variable instances method.
GET /history/variable-instance/count
Name | Description |
---|---|
variableName | Filter by variable name. |
variableNameLike | Restrict to variables with a name like the parameter. |
variableValue | Filter by variable value. Is treated as a String object on server side. |
processInstanceId | Filter by the process instance the variable belongs to. See the Introduction for the error response format. |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching historic variable instances. |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
400 | application/json | Returned if some of the query parameters are invalid. |
GET /history/variable-instance/count?variableName=my_variable
{"count": 1}
Query for historic process instances that fulfill the given parameters.
This method is slightly more powerful than the GET query, because it allows to filter by multiple process variables of types String
, Number
or Boolean
.
POST /history/process-instance
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. |
A json object with the following properties:
Name | Description |
---|---|
processInstanceIds | Filter by process instance ids. Must be a comma-separated list of process instance ids. |
processInstanceBusinessKey | Filter by process instance business key. |
superProcessInstanceId | Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id. |
processDefinitionId | Filter by the process definition the instances run on. |
processDefinitionKey | Filter by the key of the process definition the instances run on. |
processDefinitionKeyNotIn | Exclude instances that belong to a set of process definitions. Must be a comma-separated list of process definition keys. |
finished | Only include finished process instances. Values may be true or false . |
unfinished | Only include unfinished process instances. Values may be true or false . |
startedBy | Only include process instances that were started by the given user. |
startedBefore | Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
startedAfter | Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
finishedBefore | Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
finishedAfter | Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
variables | A json array to only include process instances that have/had variables with certain values. The array consists of objects with the three properties name , operator and value .
name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.value may be String , Number or Boolean .
Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
sortBy | Sort the results by a given criterion. Valid values are
instanceId , definitionId , businessKey , startTime , endTime , duration .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json array of historic process instance objects. Each historic process instance object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The id of the process instance. |
superProcessInstanceId | String | The id of the parent process instance if exists. |
processDefinitionId | String | The id of the process definition that this process instance belongs to. |
businessKey | String | The business key of the process instance. |
startTime | String | The time the instance was started. Has the format yyyy-MM-dd'T'HH:mm:ss . |
endTime | String | The time the instance ended. Has the format yyyy-MM-dd'T'HH:mm:ss . |
durationInMillis | Number | The time the instance took to finish (in milliseconds). |
startUserId | String | The id of the user who started the process instance. |
startActivityId | String | The id of the initial activity that was executed (e.g., a start event). |
deleteReason | String | The provided delete reason in case the process instance was cancelled during execution. |
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. |
POST /history/process-instance
Request body:
{"variables":
[{"name": "myVariable",
"operator": "eq",
"value": "camunda"
},
{"name": "mySecondVariable",
"operator": "neq",
"value": 124}],
"finishedAfter":"2013-01-01T00:00:00",
"finishedAfter":"2013-04-01T23:59:59"}
[{"id": "aProcInstId",
"businessKey": "aKey",
"processDefinitionId": "aProcDefId",
"startTime": "2013-03-23T13:42:43",
"endTime": "2013-03-23T13:42:45",
"durationInMillis": 2000,
"startUserId": "aStartUserId",
"startActivityId": "aStartActivityId",
"deleteReason": "aDeleteReason",
"superProcessInstanceId": "aSuperProcessInstanceId"}]
Query for the number of historic process instances that fulfill the given parameters. This method takes the same message body as the POST query and is thus slightly more powerful than the GET query count.
POST /history/process-instance/count
A json object with the following properties:
Name | Description |
---|---|
processInstanceIds | Filter by process instance ids. Must be a comma-separated list of process instance ids. |
processInstanceBusinessKey | Filter by process instance business key. |
superProcessInstanceId | Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id. |
processDefinitionId | Filter by the process definition the instances run on. |
processDefinitionKey | Filter by the key of the process definition the instances run on. |
processDefinitionKeyNotIn | Exclude instances that belong to a set of process definitions. Must be a comma-separated list of process definition keys. |
finished | Only include finished process instances. Values may be true or false . |
unfinished | Only include unfinished process instances. Values may be true or false . |
startedBy | Only include process instances that were started by the given user. |
startedBefore | Restrict to instances that were started before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
startedAfter | Restrict to instances that were started after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
finishedBefore | Restrict to instances that were finished before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
finishedAfter | Restrict to instances that were finished after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
variables | A json array to only include process instances that have/had variables with certain values. The array consists of objects with the three properties name , operator and value .
name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.value may be String , Number or Boolean .
Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching historic process instances. |
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. |
POST /history/process-instance/count
Request body:
{"variables":
[{"name": "myVariable",
"operator": "eq",
"value": "camunda"
},
{"name": "mySecondVariable",
"operator": "neq",
"value": 124}],
"finishedAfter":"2013-01-01T00:00:00",
"finishedAfter":"2013-04-01T23:59:59"}
{"count": 1}
Query for historic variable instances that fulfill the given parameters.
This method is slightly more powerful than the GET query, because it allows to filter by variable values of the different types String
, Number
or Boolean
.
POST /history/variable-instance
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. |
A json object with the following properties:
Name | Description |
---|---|
variableName | Filter by variable name. |
variableNameLike | Restrict to variables with a name like the parameter. |
variableValue | Filter by variable value. May be String , Number or Boolean . |
processInstanceId | Filter by the process instance the variable belongs to. |
sortBy | Sort the results by a given criterion. Valid values are instanceId , variableName .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json array of historic variable instance objects. Each historic activity instance object has the following properties:
Name | Value | Description |
---|---|---|
name | String | The name of the variable instance. |
type | String | The type of the variable instance. |
value | String | The value of the variable instance. |
processInstanceId | String | The id the process instance belongs to. |
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. |
POST /history/variable-instance
Request body:
{"variableValue": 42,
"variableName":"someVariable"}
[{"name": "someVariable",
"type": "Integer",
"value": 42,
"processInstanceId": "aProcInstId"}]
Query for historic variable instances that fulfill the given parameters. This method takes the same message body as the POST query and is thus more powerful regarding variable values than the GET query count method.
POST /history/variable-instance/count
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. |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching historic variable instances. |
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. |
POST /history/variable-instance/count
Request body:
{"variableValue": 42,
"variableName":"someVariable"}
{"count" : 1}
Gets the groups of a user and all users that share a group with the given user.
GET /identity/groups
Name | Description |
---|---|
userId | The id of the user to get the groups for. |
A json object containing groups, the number of members and other users. Its properties are as follows:
Name | Value | Description |
---|---|---|
groups | Array | A json array of group object. Every group object has an id property and a name property. |
groupUsers | Array | A json array that contains all users that are member in one of the groups. Every user object has four properties: id , firstName , lastName and displayName .
The displayName is the id , if firstName and lastName are null
and firstName lastName otherwise. |
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. |
GET /identity/groups?userId=aUserId
{"groups":
[{"id":"group1Id",
"name":"group1"}],
"groupUsers":
[{"firstName":"firstName",
"lastName":"lastName",
"displayName":"firstName lastName",
"id":"anotherUserId"}]}
Retrieves a single job according to the Job
interface in the engine.
GET /job/{id}
Name | Description |
---|---|
id | The id of the job to be retrieved. |
A json object corresponding to the Job interface in the engine. Its properties are as follows:
Name | Value | Description |
---|---|---|
id | String | The id of the job. |
dueDate | String | The date on which this job is supposed to be processed. |
processInstanceId | String | The id of the process instance which execution created the job. |
executionId | String | The specific execution id on which the job was created. |
retries | Number | The number of retries this job has left. |
exceptionMessage | String | The message of the exception that occurred, the last time the job was executed. Is null when no exception occurred. |
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. |
GET /job/aJobId
{
"id": "aJobId",
"dueDate": "2013-07-17'T'17:00:00",
"processInstanceId": "aProcessInstanceId",
"executionId": "anExecutionId",
"retries": 0,
"exceptionMessage": "An exception Message"
}
Retrieves the corresponding exception stacktrace to the passed job id.
GET /job/{id}/stacktrace
Name | Description |
---|---|
id | The id of the job to get the exception stacktrace for. |
The result is the corresponding stacktrace as a plain text.
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. |
GET /job/aJobId/stacktrace
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)
...
Query for jobs that fulfill given parameters. The size of the result set can be retrieved by using the get jobs count method.
GET /job
Name | Description |
---|---|
jobId | Filter by job id. |
processInstanceId | Only select jobs which exist for the given process instance. |
executionId | Only select jobs which exist for the given execution. |
withRetriesLeft | Only select jobs which have retries left. |
executable | Only select jobs which are executable, i.e., retries > 0 and duedate is null or duedate is in the past. |
timers | Only select jobs that are timers. Cannot be used together with messages . |
messages | Only select jobs that are messages. Cannot be used together with timers . |
dueDates | Only select jobs where the duedate is lower or higher than the given date.
Due date expressions are comma-separated and are structured as follows: A valid condition value has the form operator_value .
op is the comparison operator to be used and value the date value as string.Valid operator values are: gt - greater than; lt - lower than.value may not contain underscore or comma characters.
|
withException | Only select jobs that failed due to an exception. Valid value is a boolean . |
exceptionMessage | Only select jobs that failed due to an exception with the given message. |
noRetriesLeft | Only select jobs which have no retries left. |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
jobId , executionId , processInstanceId , jobRetries and jobDueDate .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
A json array of job objects. Each job object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The id of the job. |
dueDate | String | The date on which this job is supposed to be processed. |
processInstanceId | String | The id of the process instance which execution created the job. |
executionId | String | The specific execution id on which the job was created. |
retries | Number | The number of retries this job has left. |
exceptionMessage | String | The message of the exception that occurred, the last time the job was executed. Is null when no exception occurred. |
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. |
GET /job?dueDates=gt_2012-07-17'T'17:00:00,lt_2012-07-17'T'18:00:00
[
{
"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"
}
]
Query for the number of jobs that fulfill given parameters. Takes the same parameters as the get jobs method.
GET /job/count
Name | Description |
---|---|
jobId | Filter by job id. |
processInstanceId | Only select jobs which exist for the given process instance. |
executionId | Only select jobs which exist for the given execution. |
withRetriesLeft | Only select jobs which have retries left. |
executable | Only select jobs which are executable, i.e., retries > 0 and duedate is null or duedate is in the past. |
timers | Only select jobs that are timers. Cannot be used together with messages . |
messages | Only select jobs that are messages. Cannot be used together with timers . |
dueDates | Only select jobs where the duedate is lower or higher than the given date.
Due date expressions are comma-separated and are structured as follows: A valid condition value has the form operator_value .
op is the comparison operator to be used and value the date value as string.Valid operator values are: gt - greater than; lt - lower than.value may not contain underscore or comma characters.
|
withException | Only select jobs that failed due to an exception. Valid value is a boolean . |
exceptionMessage | Only select jobs that failed due to an exception with the given message. |
noRetriesLeft | Only select jobs which have no retries left. |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
jobId , executionId , processInstanceId , jobRetries and jobDueDate .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching executions. |
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. |
GET /job?dueDates=gt_2012-07-17'T'17:00:00,lt_2012-07-17'T'18:00:00
{"count": 2}
Executes the job. Note: The execution of the job happens in synchronously in the same thread.
POST /job/{id}/execute
Name | Description |
---|---|
id | The id of the job to be executed. |
This method returns no content.
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. |
PUT /job/aJobId/execute
Status 204. No content.
Query for jobs that fulfill given parameters. This method is slightly more powerful than the GET query, because it allows to filter by multiple jobs of types String
, Number
or Boolean
.
POST /job
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. |
A json object with the following properties:
Name | Description |
---|---|
jobId | Filter by job id. |
processInstanceId | Only select jobs which exist for the given process instance. |
executionId | Only select jobs which exist for the given execution. |
withRetriesLeft | Only select jobs which have retries left. Valid value is a boolean . |
executable | Only select jobs which are executable, ie. retries > 0 and duedate is null or duedate is in the past. Valid value is a boolean . |
timers | Only select jobs that are timers. Cannot be used together with messages . Valid value is a boolean . |
messages | Only select jobs that are messages. Cannot be used together with timers . Valid value is a boolean . |
dueDates | Only select jobs where the duedate is lower or higher than the given date.
Due date expressions are comma-separated and are structured as follows: A valid condition value has the form operator_value .
op is the comparison operator to be used and value the date value as string.Valid operator values are: gt - greater than; lt - lower than.value may not contain underscore or comma characters.
|
withException | Only select jobs that failed due to an exception. Valid value is a boolean . |
exceptionMessage | Only select jobs that failed due to an exception with the given message. |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
jobId , executionId , processInstanceId , jobRetries and jobDueDate .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json array of job objects. Each job object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The id of the job. |
dueDate | String | The date on which this job is supposed to be processed. |
processInstanceId | String | The id of the process instance which execution created the job. |
executionId | String | The specific execution id on which the job was created. |
retries | Number | The number of retries this job has left. |
exceptionMessage | String | The message of the exception that occurred, the last time the job was executed. Is null when no exception occurred. |
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. |
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"
}
]
}
[
{
"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"
}
]
Query for jobs that fulfill given parameters. This method takes the same message body as the POST query and is thus slightly more powerful than the GET query count.
POST /job/count
A json object with the following properties:
Name | Description |
---|---|
jobId | Filter by job id. |
processInstanceId | Only select jobs which exist for the given process instance. |
executionId | Only select jobs which exist for the given execution. |
withRetriesLeft | Only select jobs which have retries left. Valid value is a boolean . |
executable | Only select jobs which are executable, ie. retries > 0 and duedate is null or duedate is in the past. Valid value is a boolean . |
timers | Only select jobs that are timers. Cannot be used together with messages . Valid value is a boolean . |
messages | Only select jobs that are messages. Cannot be used together with timers . Valid value is a boolean . |
dueDates | Only select jobs where the duedate is lower or higher than the given date.
Due date expressions are comma-separated and are structured as follows: A valid condition value has the form operator_value .
op is the comparison operator to be used and value the date value as string.Valid operator values are: gt - greater than; lt - lower than.value may not contain underscore or comma characters.
|
withException | Only select jobs that failed due to an exception. Valid value is a boolean . |
exceptionMessage | Only select jobs that failed due to an exception with the given message. |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
jobId , executionId , processInstanceId , jobRetries and jobDueDate .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching executions. |
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. |
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"
}
]
}
{"count": 2}
Updates the due date of a job.
PUT /job/{id}/duedate
Name | Description |
---|---|
id | The id of the job to be updated. |
A json object with the following properties:
Name | Description |
---|---|
duedate | The date to set when the job has the next execution. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. | |
404 | application/json | Job with given id does not exist. See the Introduction for the error response format. |
500 | application/json | The duedate could not be set successfully. See the Introduction for the error response format. |
PUT /job/aJobId/duedate
Request body:
{"duedate": "2013-08-13 18:43:28"}
Status 204. No content.
Sets the retries of the job to the given number of retries.
PUT /job/{id}/retries
Name | Description |
---|---|
id | The id of the job to be updated. |
A json object with the following properties:
Name | Description |
---|---|
retries | The number of retries to set that a job has left. |
This method returns no content.
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. |
PUT /job/aJobId/retries
Request body:
{"retries": 3}
Status 204. No content.
Deliver a message to the process engine to either trigger a message start or intermediate message catching event.
Internally, this maps to the engine's RuntimeService#correlateMessage
methods.
See more on the correlation behavior in the message event documentation.
POST /message
A json object with the following properties:
Name | Description |
---|---|
messageName | The name of the message to deliver. |
businessKey | Used for correlation of process instances that wait for incoming messages. Will only correlate to executions that belong to a process instance with the provided business key. |
correlationKeys | Used for correlation of process instances that wait for incoming messages.
Has to be a json object containg key-value pairs that are matched against process instance variables during correlation. Each key is a variable name and each value a json variable value object. A variable value object has the property value , which is the value to update, and type , which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date.
Note: Process instance variables are the global variables of a process instance.
Local variables of child executions (such as in subprocesses) are not considered! |
processVariables | A map of variables that is injected into the triggered execution or process instance after the message has been delivered.
Each key is a variable name and each value a json variable value object. A variable value object has the property value , which is the value to update, and type , which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. | |
400 | application/json | No messageName was supplied or the message has not been correlated to exactly one entity (execution or process definition). Or the variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
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"}
}}
Status 204. No content.
Retrieves a single process definition according to the ProcessDefinition interface in the engine.
GET /process-definition/{id}
Name | Description |
---|---|
id | The id of the process definition to be retrieved. |
A json object corresponding to the ProcessDefinition interface in the engine. Its properties are as follows:
Name | Value | Description |
---|---|---|
id | String | The id of the process definition. |
key | String | The key of the process definition, i.e., the id of the BPMN 2.0 XML process definition. |
category | String | The category of the process definition. |
description | String | The description of the process definition. |
name | String | The name of the process definition. |
version | Number | The version of the process definition that the engine assigned to it. |
resource | String | The file name of the process definition. |
deploymentId | String | The id of the process definition. |
diagram | String | The file name of the process definition diagram, if exists. |
suspended | Boolean | A flag indicating whether the definition is suspended. |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
404 | application/json | Process definition with given id does not exist. See the Introduction for the error response format. |
GET /process-definition/aProcessDefinitionId
{"id":"aProcessDefinitionId",
"key":"aKey",
"category":"aCategory",
"description":"aDescription",
"name":"aName",
"version":42,
"resource":"aResourceName",
"deploymentId":"aDeploymentId",
"diagram":"aResourceName",
"suspended":true}
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.
GET /process-definition/{id}/statistics
Name | Description |
---|---|
id | The id of the process definition. |
Name | Description |
---|---|
failedJobs | Whether to include the number of failed jobs in the result or not. Valid values are true or false . |
incidents | Valid values for this property are true or false . If this property has been set to true the result will include for each occurred incident type the corresponding number of incidents. In the case of false the incidents will not be included in the result. |
incidentsForType | If this property has been set with any incident type (i.e., a String value) the result will only include the number of incidents for the assigned incident type. |
Note: The query parameters incidents
and incidentsForType
are exclusive. It is not possible to send a request with both query parameters. In that case the response will be a bad request.
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:
incidents or incidentsForType were excluded. Furthermore, the array will be also empty, if no incidents were found.
|
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. |
failedJobs=true
GET /process-definition/aProcessDefinitionId/statistics?failedJobs=true
[{"id":"anActivity",
"instances":123,
"failedJobs":42,
"incidents": []
},
{"id":"anotherActivity",
"instances":124,
"failedJobs":43,
"incidents": []}]
incidents=true
GET /process-definition/aProcessDefinitionId/statistics?incidents=true
[{"id":"anActivity",
"instances":123,
"failedJobs":0,
"incidents":
[
{"incidentType":"failedJob", "incidentCount": 42 },
{"incidentType":"aIncident", "incidentCount": 20 }
]
},
{"id":"anotherActivity",
"instances":124,
"failedJobs":0,
"incidents":
[
{ "incidentType":"failedJob", "incidentCount": 43 },
{ "incidentType":"aIncident", "incidentCount": 22 }
{ "incidentType":"anotherIncident", "incidentCount": 15 }
]
}]
incidentsForType=aIncident
GET /process-definition/aProcessDefinitionId/statistics?incidentsForType=aIncident
[{"id":"anActivity",
"instances":123,
"failedJobs":0,
"incidents":
[
{"incidentType":"aIncident", "incidentCount": 20 }
]
},
{"id":"anotherActivity",
"instances":124,
"failedJobs":0,
"incidents": []
}]
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.
GET /process-definition
Name | Description |
---|---|
name | Filter by process definition name. |
nameLike | Filter by process definition names that the parameter is a substring of. |
deploymentId | Filter by the deployment the id belongs to. |
key | Filter by process definition key, i.e., the id in the BPMN 2.0 XML. Exact match. |
keyLike | Filter by process definition keys that the parameter is a substring of. |
category | Filter by process definition category. Exact match. |
categoryLike | Filter by process definition categories that the parameter is a substring of. |
ver | Filter by process definition version. |
latest | Only include those process definitions that are latest versions. Values may be true or false . |
resourceName | Filter by the name of the process definition resource. Exact match. |
resourceNameLike | Filter by names of those process definition resources that the parameter is a substring of. |
startableBy | Filter by a user name who is allowed to start the process. |
active | Only include active process definitions. Values may be true or false . |
suspended | Only include suspended process definitions. Values may be true or false . |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
category , key , id , name , version and deploymentId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
A json array of process definition objects. Each process definition object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The id of the process definition. |
key | String | The key of the process definition, i.e., the id of the BPMN 2.0 XML process definition. |
category | String | The category of the process definition. |
description | String | The description of the process definition. |
name | String | The name of the process definition. |
version | Number | The version of the process definition that the engine assigned to it. |
resource | String | The file name of the process definition. |
deploymentId | String | The id of the process definition. |
diagram | String | The file name of the process definition diagram, if exists. |
suspended | Boolean | A flag indicating whether the definition is suspended. |
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. |
GET /process-definition?keyLike=Key&sortBy=category&sortOrder=asc
[{"id":"aProcessDefinitionId",
"key":"aKey",
"category":"aCategory",
"description":"aDescription",
"name":"aName",
"version":42,
"resource":"aResourceName",
"deploymentId":"aDeploymentId",
"diagram":"aResourceName",
"suspended":true}]
Request the number of process definitions that fulfill the query criteria. Takes the same filtering parameters as the GET query.
GET /process-definition/count
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 . |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching process definitions. |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
400 | application/json | Returned of some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy . See the Introduction for the error response format. |
GET /process-definition/count?keyLike=Key&version=47
{"count": 1}
Retrieves the key of the start form for a process definition. The form key corresponds to the FormData#formKey
property in the engine.
GET /process-definition/{id}/startForm
Name | Description |
---|---|
id | The id of the process definition to get the start form for. |
A json object containing the form key.
Name | Value | Description |
---|---|---|
key | String | The for key for the task. |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
400 | application/json | Process definition with given id does not exist or has no start form defined. See the Introduction for the error response format. |
GET /process-definition/anId/startForm
{"key":"aFormKey"}
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.
GET /process-definition/statistics
Name | Description |
---|---|
failedJobs | Whether to include the number of failed jobs in the result or not. Valid values are true or false . |
incidents | Valid values for this property are true or false . If this property has been set to true the result will include for each occurred incident type the corresponding number of incidents. In the case of false the incidents will not be included in the result. |
incidentsForType | If this property has been set with any incident type (i.e., a string value) the result will only include the number of incidents for the assigned incident type. |
Note: The query parameters incidents
and incidentsForType
are exclusive. It is not possible to send a request with both query parameters. In that case the response will be a bad request.
A json array containing statistics results per process definition. Each object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The id of the process definition the results are aggregated for. |
instances | Number | The total number of running process instances of this process definition. |
failedJobs | Number | The total number of failed jobs for the running instances. Note: Will be 0 (not null ), if failed jobs were excluded. |
definition | Object | The process definition with the properties as described in the [get single definition](ref:#process-definition-get-single-definition) method. |
incidents | Array | Each item in the resulting array is an object which contains the following properties:
incidents or incidentsForType were excluded. Furthermore, the array will be also empty, if no incidents were found.
|
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. |
failedJobs=true
GET /process-definition/statistics?failedJobs=true
[{"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:" []
}]
incidents=true
GET /process-definition/statistics?incidents=true
[{"id":"aProcessDefinitionId",
"instances":123,
"failedJobs":0,
"definition":
{"id":"aProcessDefinitionId",
"key":"aKey",
"category":null,
"description":null,
"name":"aName",
"version":0,
"resource":null,
"deploymentId":null,
"diagram":null,
"suspended":false},
"incidents":
[
{"incidentType":"failedJob", "incidentCount": 42 },
{"incidentType":"aIncident", "incidentCount": 20 }
]
},
{"id":"aProcessDefinitionId:2",
"instances":124,
"failedJobs":0,
"definition":
{"id":"aProcessDefinitionId:2",
"key":"aKey",
"category":null,
"description":null,
"name":"aName",
"version":0,
"resource":null,
"deploymentId":null,
"diagram":null,
"suspended":false},
"incidents":
[
{ "incidentType":"failedJob", "incidentCount": 43 },
{ "incidentType":"aIncident", "incidentCount": 22 }
{ "incidentType":"anotherIncident", "incidentCount": 15 }
]
}]
incidentsForType=aIncident
GET /process-definition/statistics?incidentsForType=aIncident
[{"id":"aProcessDefinitionId",
"instances":123,
"failedJobs":0,
"definition":
{"id":"aProcessDefinitionId",
"key":"aKey",
"category":null,
"description":null,
"name":"aName",
"version":0,
"resource":null,
"deploymentId":null,
"diagram":null,
"suspended":false},
"incidents":
[
{"incidentType":"aIncident", "incidentCount": 20 }
]
},
{"id":"aProcessDefinitionId:2",
"instances":124,
"failedJobs":0,
"definition":
{"id":"aProcessDefinitionId:2",
"key":"aKey",
"category":null,
"description":null,
"name":"aName",
"version":0,
"resource":null,
"deploymentId":null,
"diagram":null,
"suspended":false},
"incidents": []
}]
Retrieves the BPMN 2.0 XML of this process definition.
GET /process-definition/{id}/xml
Name | Description |
---|---|
id | The id of the process definition. |
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. |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
400 | application/json | Process definition with given id does not exist. See the Introduction for the error response format. |
GET /process-definition/aProcessDefinitionId/xml
{"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
..."}
Instantiates a given process definition. Process variables may be supplied in the request body.
POST /process-definition/{id}/start
Name | Description |
---|---|
id | The id of the process definition to be retrieved. |
A json object with the following properties:
Name | Description |
---|---|
variables | A json object containing the variables the process is to be initialized with.
Variable names are property keys of this object and variable values are json objects with a value and a type property (see example below).
Valid variable values are Boolean, Number, String and Date values. |
A json object representing the newly created process instance. Properties are:
Name | Value | Description |
---|---|---|
id | String | The id of the process instance. |
definitionId | String | The id of the process definition. |
businessKey | String | The business key of the process instance. |
ended | Boolean | A flag indicating whether the instance is still running. |
suspended | Boolean | A flag indicating whether the instance is suspended. |
links | Object | A json array containing links to interact with the instance. |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
400 | application/json | The instance could not be created due to an invalid variable value. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
500 | application/json | The instance could not be created successfully. See the Introduction for the error response format. |
POST /process-definition/aProcessDefinitionId/start
Request body:
{"variables":
{"aVariable" : {"value" : "aStringValue", "type": "String"},
"anotherVariable" : {"value" : true, "type": "Boolean"}}}
{"links":[{"method": "GET", "href":"http://localhost:8080/rest-test/process-instance/anId","rel":"self"}],
"id":"anId",
"definitionId":"aProcessDefinitionId",
"businessKey":null,
"ended":false,
"suspended":false}
Deletes a running process instance.
DELETE /process-instance/{id}
Name | Description |
---|---|
id | The id of the process instance to be retrieved. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | application/json | Request successful. |
404 | application/json | Process instance with given id does not exist. See the Introduction for the error response format. |
DELETE /process-instance/aProcessInstanceId
Status 204. No content.
Deletes a variable of a given process instance.
DELETE /process-instance/{id}/variables/{varId}
Name | Description |
---|---|
id | The id of the process instance to delete the variable from. |
varId | The name of the variable to delete. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. |
DELETE /process-instance/aProcessInstanceId/variables/aVarName
Status 204. No content.
Retrieves a single process instance according to the ProcessInstance
interface in the engine.
GET /process-instance/{id}
Name | Description |
---|---|
id | The id of the process instance to be retrieved. |
A json object corresponding to the ProcessInstance interface in the engine. Its properties are as follows:
Name | Value | Description |
---|---|---|
id | String | The id of the process instance. |
definitionId | String | The id of the process definition this instance belongs to. |
businessKey | String | The business key of the process instance. |
ended | Boolean | A flag indicating whether the process instance has ended. |
suspended | Boolean | A flag indicating whether the process instance is suspended. |
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. |
GET /process-instance/aProcessInstanceId
{"id":"aProcessInstanceId",
"definitionId":"aProcDefId",
"businessKey":"aKey",
"ended":false,
"suspended":false}
Retrieves an Activity Instance (Tree) for a given process instance.
GET /process-instance/{id}/activity-instances
Name | Description |
---|---|
id | The id of the process instance for which the activity instance should be retrieved. |
A json object corresponding to the Activity Instance tree of the given process instance.
The properties of an activity instance are as follows:
Name | Value | Description |
---|---|---|
id | String | The id of the activity instance. |
activityId | String | The id of activity. |
processInstanceId | String | The id of the process instance this activity instance is part of. |
processDefinitionId | String | The id of the process definition. |
childActivityInstances | List of activityInstance | A list of child activity instances. |
childTransitionInstances | List of transitionInstance | A list of child transition instances. A transition instance represents an execution waiting in an asynchronous continuation. |
executionIds | List of String | A list of execution ids. |
The properties of a transition instance are as follows:
Name | Value | Description |
---|---|---|
id | String | The id of the transition instance. |
activityId | String | The id of activity that is about to be entered |
processInstanceId | String | The id of the process instance. |
processDefinitionId | String | The id of the process definition. |
executionId | List of String | A list of execution ids. |
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. |
GET /process-instance/aProcessInstanceId/activity-instances
{
"id": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
"parentActivityInstanceId": null,
"activityId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
"processInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
"processDefinitionId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
"childActivityInstances": [
{
"id": "SubProcess_1:8f72bca4-d505-11e2-bafa-3c970e140ef1",
"parentActivityInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
"activityId": "SubProcess_1",
"processInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
"processDefinitionId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
"childActivityInstances": [],
"childTransitionInstances": [
{
"id": "8f72bca9-d505-11e2-bafa-3c970e140ef1",
"parentActivityInstanceId": "SubProcess_1:8f72bca4-d505-11e2-bafa-3c970e140ef1",
"processInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
"processDefinitionId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
"targetActivityId": "ServiceTask_1",
"executionId": "8f72bca9-d505-11e2-bafa-3c970e140ef1"
},
{
"id": "8f72bcaa-d505-11e2-bafa-3c970e140ef1",
"parentActivityInstanceId": "SubProcess_1:8f72bca4-d505-11e2-bafa-3c970e140ef1",
"processInstanceId": "8f72bc9f-d505-11e2-bafa-3c970e140ef1",
"processDefinitionId": "executionProcess:1:8ef5c393-d505-11e2-bafa-3c970e140ef1",
"targetActivityId": "ServiceTask_2",
"executionId": "8f72bcaa-d505-11e2-bafa-3c970e140ef1"
}
],
"executionIds": [
"8f72bc9f-d505-11e2-bafa-3c970e140ef1"
]
}
],
"childTransitionInstances": [],
"executionIds": [
"8f72bc9f-d505-11e2-bafa-3c970e140ef1"
]
}
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.
GET /process-instance
Name | Description |
---|---|
processInstanceIds | Filter by a comma-separated list of process instance ids. |
businessKey | Filter by process instance business key. |
processDefinitionId | Filter by the process definition the instances run on. |
processDefinitionKey | Filter by the key of the process definition the instances run on. |
superProcessInstance | Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id. |
subProcessInstance | Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id. |
active | Only include active process instances. Values may be true or false . |
suspended | Only include suspended process instances. Values may be true or false . |
variables | Only include process instances that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
sortBy | Sort the results lexicographically by a given criterion. Valid values are
instanceId , definitionKey and definitionId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
A json array of process instance objects. Each process instance object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The id of the process instance. |
definitionId | String | The id of the process definition that this process instance belongs to. |
businessKey | String | The business key of the process instance. |
ended | Boolean | A flag indicating whether the process instance has ended. |
suspended | Boolean | A flag indicating whether the process instance is suspended. |
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. |
GET /process-instance?variables=myVariable_eq_camunda,mySecondVariable_neq_aBadValue
[{"links":[],
"id":"anId",
"definitionId":"aProcDefId",
"businessKey":"aKey",
"ended":false,
"suspended":false}]
Query for the number of process instances that fulfill given parameters. Takes the same parameters as the get instances method.
GET /process-instance/count
Name | Description |
---|---|
processInstanceIds | Filter by a comma-separated list of process instance ids. |
businessKey | Filter by process instance business key. |
processDefinitionId | Filter by the process definition the instances run on. |
processDefinitionKey | Filter by the key of the process definition the instances run on. |
superProcessInstance | Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id. |
subProcessInstance | Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id. |
active | Only include active process instances. Values may be true or false . |
suspended | Only include suspended process instances. Values may be true or false . |
variables | Only include process instances that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching process instances. |
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. |
GET /process-instance/count?variables=myVariable_eq_camunda
{"count": 1}
Retrieves a variable of a given process instance.
GET /process-instance/{id}/variables/{varId}
Name | Description |
---|---|
id | The id of the process instance to retrieve the variable for. |
varId | The name of the variable to get. |
A json object with the following properties:
Name | Value | Description |
---|---|---|
value | String/Number/Boolean/Object | Object serialization uses Jackson's POJO/bean property introspection feature. |
type | String | The simple class name of the variable object. |
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. |
GET /process-instance/aProcessInstanceId/variables/aVarName
{"value" : "someValue",
"type" : "String"}
Retrieves all variables of a given process instance.
GET /process-instance/{id}/variables
Name | Description |
---|---|
id | The id of the process instance to retrieve the variables for. |
A json object of variables key-value pairs. Each key is a variable name and each value a variable value object that has the following properties:
Name | Value | Description |
---|---|---|
value | String/Number/Boolean/Object | Object serialization uses Jackson's POJO/bean property introspection feature. |
type | String | The simple class name of the variable object. |
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. |
GET /process-instance/aProcessInstanceId/variables
{"aProcessVariableKey":
{"value":
{"property1":"aPropertyValue",
"property2":true},
"type":"ExampleVariableObject"}}}
Query for process instances that fulfill given parameters through a json object.
This method is slightly more powerful than the GET query, because it allows
to filter by multiple process variables of types String
, Number
or Boolean
.
POST /process-instance
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. |
A json object with the following properties:
Name | Description |
---|---|
processInstanceIds | Filter by a list of process instance ids. Must be a json array of Strings. |
businessKey | Filter by process instance business key. |
processDefinitionId | Filter by the process definition the instances run on. |
processDefinitionKey | Filter by the key of the process definition the instances run on. |
superProcessInstance | Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id. |
subProcessInstance | Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id. |
active | Only include active process instances. Values may be true or false . |
suspended | Only include suspended process instances. Values may be true or false . |
variables | A json array to only include process instances that have variables with certain values. The array consists of objects with the three properties name , operator and value .
name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.value may be String , Number or Boolean .
Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
instanceId , definitionKey and definitionId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json array of process instance objects. Each process instance object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The id of the process instance. |
definitionId | String | The id of the process definition that this process instance belongs to. |
businessKey | String | The business key of the process instance. |
ended | Boolean | A flag indicating whether the process instance has ended. |
suspended | Boolean | A flag indicating whether the process instance is suspended. |
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. |
POST /process-instance
Request body:
{"variables":
[{"name": "myVariable",
"operator": "eq",
"value": "camunda"
},
{"name": "mySecondVariable",
"operator": "neq",
"value": 124}],
"processDefinitionId":"aProcessDefinitionId"}
[{"links":[],
"id":"anId",
"definitionId":"aProcessDefinitionId",
"businessKey":"aKey",
"ended":false,
"suspended":false}]
Query for the number of process instances that fulfill the given parameters. This method takes the same message body as the POST query and is thus slightly more powerful than the GET query count.
POST /process-instance/count
A json object with the following properties:
Name | Description |
---|---|
processInstanceIds | Filter by a list of process instance ids. Must be a json array of Strings. |
businessKey | Filter by process instance business key. |
processDefinitionId | Filter by the process definition the instances run on. |
processDefinitionKey | Filter by the key of the process definition the instances run on. |
superProcessInstance | Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id. |
subProcessInstance | Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id. |
active | Only include active process instances. Values may be true or false . |
suspended | Only include suspended process instances. Values may be true or false . |
variables | A json array to only include process instances that have variables with certain values. The array consists of objects with the three properties key , operator and value .
key (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.value may be String , Number or Boolean .
Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching process instances. |
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. |
POST /process-instance/count
Request body:
{"variables":
[{"name": "myVariable",
"operator": "eq",
"value": "camunda"
},
{"name": "mySecondVariable",
"operator": "neq",
"value": 124}],
"processDefinitionId":"aProcessDefinitionId"}
{"count": 1}
Updates or deletes the variables of a process instance. Updates precede deletes. So if a variable is updated AND deleted, the deletion overrides the update.
POST /process-instance/{id}/variables
Name | Description |
---|---|
id | The id of the process instance to set variables for. |
A json object with the following properties:
Name | Description |
---|---|
modifications | A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object.
A variable value object has has the property value , which is the value to update, and type , which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. |
deletions | An array of String keys of variables to be deleted. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | application/json | Request successful. |
400 | application/json | The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
500 | application/json | Update or delete could not be executed, for example because the process instance does not exist. |
POST /process-instance/aProcessInstanceId/variables
Request body:
{"modifications":
{"aVariable": {"value": "aValue"},
"anotherVariable": {"value": 42}},
"deletions": [
"aThirdVariable", "FourthVariable"
]}
Status 204. No content.
Activate or suspend a given process instance.
PUT /process-instance/{id}/suspended
Name | Description |
---|---|
id | The id of the process instance to activate or suspend. |
A json object with the following properties:
Name | Description |
---|---|
suspended | A Boolean value which indicates whether to activate or suspend a given process instance. When the value is set to true , then the given process instance will be suspended and when the value is set to false , then the given process instance will be activated. |
This method returns no content.
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. |
PUT /process-instance/aProcessInstanceId/suspended
{"suspended" : true}
Status 204. No content.
Sets a variable of a given process instance.
PUT /process-instance/{id}/variables/{varId}
Name | Description |
---|---|
id | The id of the process instance to set the variable for. |
varId | The name of the variable to set. |
A json object with the following properties:
Name | Description |
---|---|
value | The value of the variable to set. |
type | The type of the variable to set. Valid types are Integer, Short, Long, Double, String, Boolean and Date. |
This method returns no content.
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. |
PUT /process-instance/aProcessInstanceId/variables/aVarName
{"value" : "someValue", "type": "String"}
Status 204. No content.
Retrieves a single task by its id.
GET /task/{id}
Name | Description |
---|---|
id | The id of the task to be retrieved. |
A json object corresponding to the Task interface in the engine. Its properties are as follows:
Name | Value | Description |
---|---|---|
id | String | The id of the task. |
name | String | The tasks name. |
assignee | String | The user assigned to this task. |
created | String | The time the task was created. Format yyyy-MM-dd'T'HH:mm:ss . |
due | String | The due date for the task. Format yyyy-MM-dd'T'HH:mm:ss . |
delegationState | String | The delegation state of the task. Corresponds to the DelegationState enum in the engine.
Possible values are RESOLVED and PENDING . |
description | String | The task description. |
executionId | String | The id of the execution the task belongs to. |
owner | String | The owner of the task. |
parentTaskId | String | The id of the parent task, if this task is a subtask. |
priority | Number | The priority of the task. |
processDefinitionId | String | The id of the process definition this task belongs to. |
processInstanceId | String | The id of the process instance this task belongs to. |
taskDefinitionKey | String | The task definition key. |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
404 | application/json | Task with given id does not exist. See the Introduction for the error response format. |
GET /task/anId
{"id":"anId",
"name":"aName",
"assignee":"anAssignee",
"created":"2013-01-23T13:42:42",
"due":"2013-01-23T13:42:43",
"delegationState":"RESOLVED",
"description":"aDescription",
"executionId":"anExecution",
"owner":"anOwner",
"parentTaskId":"aParentId",
"priority":42,
"processDefinitionId":"aProcDefId",
"processInstanceId":"aProcInstId",
"taskDefinitionKey":"aTaskDefinitionKey"}
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.
GET /task/{id}/form
Name | Description |
---|---|
id | The id of the task to retrieve the form for. |
A json object containing the form key.
Name | Value | Description |
---|---|---|
key | String | The for key for the task. |
contextPath | String | The process application's context path the task belongs to. If the task does not belong to a process application deployment or a process definition at all, this property is not set. |
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. |
GET /task/anId/form
{"key":"aFormKey",
"contextPath":"http://localhost:8080/my-process-application/"}
Query for tasks that fulfill a given filter. The size of the result set can be retrieved by using get tasks count method.
GET /task
Name | Description |
---|---|
processInstanceId | Restrict to tasks that belong to process instances with the given id. |
processInstanceBusinessKey | Restrict to tasks that belong to process instances with the given business key. |
processDefinitionId | Restrict to tasks that belong to a process definition with the given id. |
processDefinitionKey | Restrict to tasks that belong to a process definition with the given key. |
processDefinitionName | Restrict to tasks that belong to a process definition with the given name. |
executionId | Restrict to tasks that belong to an execution with the given id. |
activityInstanceIdIn | Only include tasks which belongs to one of the passed and comma-separated activity instance ids. |
assignee | Restrict to tasks that the given user is assigned to. |
owner | Restrict to tasks that the given user owns. |
candidateGroup | Only include tasks that are offered to the given group. |
candidateUser | Only include tasks that are offered to the given user. |
involvedUser | Only include tasks that the given user is involved in. A user is involved in a task if there exists an identity link between task and user (e.g., the user is the assignee). |
unassigned | If set to true , restricts the query to all tasks that are unassigned. |
taskDefinitionKey | Restrict to tasks that have the given key. |
taskDefinitionKeyLike | Restrict to tasks that have a key that has the parameter value as a substring. |
name | Restrict to tasks that have the given name. |
nameLike | Restrict to tasks that have a name with the given parameter value as substring. |
description | Restrict to tasks that have the given description. |
descriptionLike | Restrict to tasks that have a description that has the parameter value as a substring. |
priority | Restrict to tasks that have the given priority. |
maxPriority | Restrict to tasks that have a lower or equal priority. |
minPriority | Restrict to tasks that have a higher or equal priority. |
due | Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
dueAfter | Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
dueBefore | Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
created |
Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid.
Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero
milliseconds.
|
createdAfter | Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
createdBefore | Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
delegationState | Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED . |
candidateGroups | Restrict to tasks that are offered to any of the given candidate groups. Takes a comma-separated list of group names, so for example developers,support,sales . |
active | Only include active tasks. Values may be true or false . |
suspended | Only include suspended tasks. Values may be true or false . |
taskVariables | Only include tasks that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
processVariables | Only include tasks that belong to process instances that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
sortBy | Sort the results lexicographically by a given criterion. Valid values are
instanceId , dueDate , executionId , assignee , created ,
description , id , name and priority .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
A json array of task objects. Each task object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The task id. |
name | String | The task name. |
assignee | String | The assignee's id. |
owner | String | The owner's id. |
created | String | The date the task was created on. Has the format yyyy-MM-dd'T'HH:mm:ss . |
due | String | The task's due date. Has the format yyyy-MM-dd'T'HH:mm:ss . |
delegationState | String | The task's delegation state. Possible values are PENDING and RESOLVED . |
description | String | The task's description. |
executionId | String | The id of the execution the task belongs to. |
parentTaskId | String | The id the parent task, if this task is a subtask. |
priority | Number | The task's priority. |
processDefinitionId | String | The id of the process definition the task belongs to. |
processInstanceId | String | The id of the process instance the task belongs to. |
taskDefinitionKey | String | The task's key. |
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. |
GET /task?assignee=anAssignee&delegationState=RESOLVED&maxPriority=50
Response
[{"id":"anId",
"name":"aName",
"assignee":"anAssignee",
"created":"2013-01-23T13:42:42",
"due":"2013-01-23T13:42:43",
"delegationState":"RESOLVED",
"description":"aDescription",
"executionId":"anExecution",
"owner":"anOwner",
"parentTaskId":"aParentId",
"priority":42,
"processDefinitionId":"aProcDefId",
"processInstanceId":"aProcInstId",
"taskDefinitionKey":"aTaskDefinitionKey"}]
Get the number of tasks that fulfill a provided filter. Corresponds to the size of the result set when using the get tasks method.
GET /task/count
Name | Description |
---|---|
processInstanceId | Restrict to tasks that belong to process instances with the given id. |
processInstanceBusinessKey | Restrict to tasks that belong to process instances with the given business key. |
processDefinitionId | Restrict to tasks that belong to a process definition with the given id. |
processDefinitionKey | Restrict to tasks that belong to a process definition with the given key. |
processDefinitionName | Restrict to tasks that belong to a process definition with the given name. |
executionId | Restrict to tasks that belong to an execution with the given id. |
activityInstanceIdIn | Only include tasks which belongs to one of the passed and comma-separated activity instance ids. |
assignee | Restrict to tasks that the given user is assigned to. |
owner | Restrict to tasks that the given user owns. |
candidateGroup | Only include tasks that are offered to the given group. |
candidateUser | Only include tasks that are offered to the given user. |
involvedUser | Only include tasks that the given user is involved in. A user is involved in a task if there exists an identity link between task and user (e.g., the user is the assignee). |
unassigned | If set to true , restricts the query to all tasks that are unassigned. |
taskDefinitionKey | Restrict to tasks that have the given key. |
taskDefinitionKeyLike | Restrict to tasks that have a key that has the parameter value as a substring. |
name | Restrict to tasks that have the given name. |
nameLike | Restrict to tasks that have a name with the given parameter value as substring. |
description | Restrict to tasks that have the given description. |
descriptionLike | Restrict to tasks that have a description that has the parameter value as a substring. |
priority | Restrict to tasks that have the given priority. |
maxPriority | Restrict to tasks that have a lower or equal priority. |
minPriority | Restrict to tasks that have a higher or equal priority. |
due | Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
dueAfter | Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
dueBefore | Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
created |
Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid.
Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero
milliseconds.
|
createdAfter | Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
createdBefore | Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
delegationState | Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED . |
candidateGroups | Restrict to tasks that are offered to any of the given candidate groups. Takes a comma-separated list of group names, so for example developers,support,sales . |
active | Only include active tasks. Values may be true or false . |
suspended | Only include suspended tasks. Values may be true or false . |
taskVariables | Only include tasks that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
processVariables | Only include tasks that belong to process instances that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
A json object with a single count property.
Name | Value | Description |
---|---|---|
count | Number | The number of tasks that fulfill the query criteria. |
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. |
GET /task/count?assignee=anAssignee&delegationState=RESOLVED&maxPriority=50
{"count":1}
Change the assignee of a task to a specific user.
Note: The difference with claim a task is that this method does not check whether the task does already have a user assigned to it.
POST /task/{id}/assignee
Name | Description |
---|---|
id | The id of the task to set the assignee. |
A json object with the following properties:
Name | Description |
---|---|
userId | The id of the user that will be the assignee of the task. |
This method returns no content.
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. |
POST /task/anId/assignee
Request body:
{"userId": "aUserId"}
Status 204. No content.
Claim a task for a specific user.
Note: The difference with set a assignee is that here a check is done if the task already has a user assigned to it.
POST /task/{id}/claim
Name | Description |
---|---|
id | The id of the task to claim. |
A json object with the following properties:
Name | Description |
---|---|
userId | The id of the user that claims the task. |
This method returns no content.
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. |
POST /task/anId/claim
Request body:
{"userId": "aUserId"}
Status 204. No content.
Complete a task and update process variables.
POST /task/{id}/complete
Name | Description |
---|---|
id | The id of the task to complete. |
A json object with the following properties:
Name | Description |
---|---|
variables | A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object.
A variable value object has has the property value , which is the value to update, and type , which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. This parameter is optional and may be left out. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. | |
400 | application/json | The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
500 | application/json | If the task does not exist or the corresponding process instance could not be resumed successfully. See the Introduction for the error response format. |
POST /task/anId/complete
Request body:
{"variables":
{"aVariable": {"value": "aStringValue"},
"anotherVariable": {"value": 42},
"aThirdVariable": {"value": true}}
}
Status 204. No content.
Delegate a task to another user.
POST /task/{id}/delegate
Name | Description |
---|---|
id | The id of the task to delegate. |
A json object with the following properties:
Name | Description |
---|---|
userId | The id of the user that the task should be delegated to. |
This method returns no content.
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. |
POST /task/anId/delegate
Request body:
{"userId": "aUserId"}
Status 204. No content.
Query for tasks that fulfill a given filter.
This method is slightly more powerful than the GET query, because it allows
to filter by multiple process or task variables of types String
, Number
or Boolean
.
The size of the result set can be retrieved by using get tasks count (POST) method.
POST /task
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. |
A json object with the following properties:
Name | Description |
---|---|
processInstanceId | Restrict to tasks that belong to process instances with the given id. |
processInstanceBusinessKey | Restrict to tasks that belong to process instances with the given business key. |
processDefinitionId | Restrict to tasks that belong to a process definition with the given id. |
processDefinitionKey | Restrict to tasks that belong to a process definition with the given key. |
processDefinitionName | Restrict to tasks that belong to a process definition with the given name. |
executionId | Restrict to tasks that belong to an execution with the given id. |
activityInstanceIdIn | Only include tasks which belongs to one of the passed activity instance ids. |
assignee | Restrict to tasks that the given user is assigned to. |
owner | Restrict to tasks that the given user owns. |
candidateGroup | Only include tasks that are offered to the given group. |
candidateUser | Only include tasks that are offered to the given user. |
involvedUser | Only include tasks that the given user is involved in. A user is involved in a task if there exists an identity link between task and user (e.g., the user is the assignee). |
unassigned | If set to true , restricts the query to all tasks that are unassigned. |
taskDefinitionKey | Restrict to tasks that have the given key. |
taskDefinitionKeyLike | Restrict to tasks that have a key that has the parameter value as a substring. |
name | Restrict to tasks that have the given name. |
nameLike | Restrict to tasks that have a name with the given parameter value as substring. |
description | Restrict to tasks that have the given description. |
descriptionLike | Restrict to tasks that have a description that has the parameter value as a substring. |
priority | Restrict to tasks that have the given priority. |
maxPriority | Restrict to tasks that have a lower or equal priority. |
minPriority | Restrict to tasks that have a higher or equal priority. |
dueDate | Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
dueAfter | Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
dueBefore | Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
createdOn |
Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid.
Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero
milliseconds.
|
createdAfter | Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
createdBefore | Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
delegationState | Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED . |
candidateGroups | Restrict to tasks that are offered to any of the given candidate groups. Takes a json array of group names, so for example ["developers", "support", "sales"] . |
active | Only include active tasks. Values may be true or false . |
suspended | Only include suspended tasks. Values may be true or false . |
taskVariables | A json array to only include tasks that have variables with certain values. The array consists of json objects with three properties name , operator and value .
name is the variable name, op is the comparison operator to be used and value the variable value.value may be of type String , Number or Boolean .Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
processVariables | A json array to only include tasks that belong to a process instance with variables with certain values. The array consists of json objects with three properties name , operator and value .
name is the variable name, op is the comparison operator to be used and value the variable value.value may be of type String , Number or Boolean .Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
instanceId , dueDate , executionId , assignee , created ,
description , id , name and priority .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json array of task objects. Each task object has the following properties:
Name | Value | Description |
---|---|---|
id | String | The task id. |
name | String | The task name. |
assignee | String | The assignee's id. |
owner | String | The owner's id. |
created | String | The date the task was created on. Has the format yyyy-MM-dd'T'HH:mm:ss . |
due | String | The task's due date. Has the format yyyy-MM-dd'T'HH:mm:ss . |
delegationState | String | The task's delegation state. Possible values are PENDING and RESOLVED |
description | String | The task's description. |
executionId | String | The id of the execution the task belongs to. |
parentTaskId | String | The id the parent task, if this task is a subtask. |
priority | Number | The task's priority. |
processDefinitionId | String | The id of the process definition the task belongs to. |
processInstanceId | String | The id of the process instance the task belongs to. |
taskDefinitionKey | String | The task's key. |
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.
|
POST /task
Request body:
{"taskVariables":
[{"name": "varName",
"value": "varValue",
"operator": "eq"
},
{"name": "anotherVarName",
"value": 30,
"operator": "neq"}],
"priority":10}
[{"id":"anId",
"name":"aName",
"assignee":"anAssignee",
"created":"2013-01-23T13:42:42",
"due":"2013-01-23T13:42:43",
"delegationState":"RESOLVED",
"description":"aDescription",
"executionId":"anExecution",
"owner":"anOwner",
"parentTaskId":"aParentId",
"priority":10,
"processDefinitionId":"aProcDefId",
"processInstanceId":"aProcInstId",
"taskDefinitionKey":"aTaskDefinitionKey"}]
Get 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.
POST /task/count
A json object with the following properties:
Name | Description |
---|---|
processInstanceId | Restrict to tasks that belong to process instances with the given id. |
processInstanceBusinessKey | Restrict to tasks that belong to process instances with the given business key. |
processDefinitionId | Restrict to tasks that belong to a process definition with the given id. |
processDefinitionKey | Restrict to tasks that belong to a process definition with the given key. |
processDefinitionName | Restrict to tasks that belong to a process definition with the given name. |
executionId | Restrict to tasks that belong to an execution with the given id. |
activityInstanceIdIn | Only include tasks which belongs to one of the passed activity instance ids. |
assignee | Restrict to tasks that the given user is assigned to. |
owner | Restrict to tasks that the given user owns. |
candidateGroup | Only include tasks that are offered to the given group. |
candidateUser | Only include tasks that are offered to the given user. |
involvedUser | Only include tasks that the given user is involved in. A user is involved in a task if there exists an identity link between task and user (e.g., the user is the assignee). |
unassigned | If set to true , restricts the query to all tasks that are unassigned. |
taskDefinitionKey | Restrict to tasks that have the given key. |
taskDefinitionKeyLike | Restrict to tasks that have a key that has the parameter value as a substring. |
name | Restrict to tasks that have the given name. |
nameLike | Restrict to tasks that have a name with the given parameter value as substring. |
description | Restrict to tasks that have the given description. |
descriptionLike | Restrict to tasks that have a description that has the parameter value as a substring. |
priority | Restrict to tasks that have the given priority. |
maxPriority | Restrict to tasks that have a lower or equal priority. |
minPriority | Restrict to tasks that have a higher or equal priority. |
dueDate | Restrict to tasks that are due on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
dueAfter | Restrict to tasks that are due after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
dueBefore | Restrict to tasks that are due before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
createdOn |
Restrict to tasks that were created on the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid.
Note: if the used database saves dates with milliseconds precision this query only will return tasks created on the given timestamp with zero
milliseconds.
|
createdAfter | Restrict to tasks that were created after the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
createdBefore | Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss , so for example 2013-01-23T14:42:45 is valid. |
delegationState | Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED . |
candidateGroups | Restrict to tasks that are offered to any of the given candidate groups. Takes a json array of group names, so for example ["developers", "support", "sales"] . |
active | Only include active tasks. Values may be true or false . |
suspended | Only include suspended tasks. Values may be true or false . |
taskVariables | A json array to only include tasks that have variables with certain values. The array consists of json objects with three properties name , operator and value .
name is the variable name, op is the comparison operator to be used and value the variable value.value may be of type String , Number or Boolean .Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
processVariables | A json array to only include tasks that belong to a process instance with variables with certain values. The array consists of json objects with three properties name , operator and value .
name is the variable name, op is the comparison operator to be used and value the variable value.value may be of type String , Number or Boolean .Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
A json object with a single count property.
Name | Value | Description |
---|---|---|
count | Number | The number of tasks that fulfill the query criteria. |
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. |
POST /task/count
Request body:
{"taskVariables":
[{"name": "varName",
"value": "varValue",
"operator": "eq"
},
{"name": "anotherVarName",
"value": 30,
"operator": "neq"}],
"priority":10}
{"count":1}
Resolve a task and update execution variables.
POST /task/{id}/resolve
Name | Description |
---|---|
id | The id of the task to resolve. |
A json object with the following properties:
Name | Description |
---|---|
variables | A json object containing variable key-value pairs. Each key is a variable name and each value a json variable value object.
A variable value object has has the property value , which is the value to update, and type , which represents the type of the value. Valid types are String, Integer, Short, Long, Double and Date. This parameter is optional and may be left out. |
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. | |
400 | application/json | The variable value or type is invalid. For example the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
500 | application/json | If the task does not exist or the corresponding process instance could not be resumed successfully. See the Introduction for the error response format. |
POST /task/anId/resolve
Request body:
{"variables":
{"aVariable": {"value": "aStringValue", "type": "String"},
"anotherVariable": {"value": 42, "type": "Integer"},
"aThirdVariable": {"value": true, "type": "Boolean"}}
}
Status 204. No content.
Resets a task's assignee. If successful, the task is not assigned to a user.
POST /task/{id}/unclaim
Name | Description |
---|---|
id | The id of the task to unclaim. |
This method returns no content.
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. |
POST /task/anId/unclaim
Status 204. No content.
Deletes a user by id.
DELETE /user/{id}
Name | Description |
---|---|
id | The id of the user to be deleted. |
Empty.
This method returns no content.
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
404 | application/json | User cannot be found. See the Introduction for the error response format. |
DELETE /user/jonny1
Status 204. No content.
Retrieves a single user's profile.
GET /user/{id}/profile
Name | Description |
---|---|
id | The id of the user to be retrieved. |
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. |
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. |
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. |
GET /user/jonny1/profile
Status 200.
{"id":"jonny1",
"firstName":"John",
"lastName":"Doe",
"email":"anEmailAddress"}
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.
GET /user
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. |
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. |
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. |
String | The email of the user. |
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. |
GET /user?firstName=John
Status 200.
[{"id":"jonny1",
"firstName":"John",
"lastName":"Doe",
"email":"anEmailAddress"},
{"id":"jonny2",
"firstName":"John",
"lastName":"Smoe",
"email":"anEmailAddress"}]
Query for users using a list of parameters and retrieves the count.
GET /user/count
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. |
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. |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching users. |
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. |
GET /user/count?firstName=John
Status 200.
{"count": 2}
The /user
resource supports two custom OPTIONS requests, one for the resource as such and one for individual user instances. The options request allows checking for the set of available operations that the currently authenticated user can perform on the /user
resource. The fact whether the user can perform an operation may depend on various things, including the users authorizations to interact with this resource and the interal configuration of the process engine.
OPTIONS /user
for available interactions on resource
OPTIONS /user/{id}
for available interactions on resource instance
A Json object with a single property named links
, providing a list of resource links. Each link has the following properties
Name | Value | Description |
---|---|---|
method | String | The HTTP method to use for the interaction. |
href | String | The interaction URL |
rel | String | The relation of the interaction (i.e., a symbolic name representing the nature of the interaction). Examples: create , delete ... |
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
OPTIONS /user/aUserId
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 a new user.
POST /user/create
A json object with the following properties:
Name | Type | Description |
---|---|---|
profile | Array |
A json object containing variable key-value pairs. The object contains the following properties:
id (String) , firstName (String) , lastName (String) and email (String) .
|
credentials | Array |
A json object containing variable key-value pairs. The object contains the following properties:
password (String) .
|
This method returns no content.
Code | Media type | Description |
---|---|---|
204 | Request successful. | |
500 | application/json | The user could not be created due to an internal server error. See the Introduction for the error response format. |
POST /user/create
Request body:
{"profile":
{"id": "jonny1",
"firstName":"John",
"lastName":"Doe",
"email":"aNewEmailAddress"},
"credentials":
{"password":"s3cret"}
}
Status 204. No content.
Updates a user's credentials (password).
PUT /user/{id}/credentials
A json object with the following properties:
Name | Type | Description |
---|---|---|
password | String | The user's new password. |
authenticatedUserPassword | String | The password of the authenticated user who changes the password of the user (i.e., the user with passed id as path parameter). |
Empty.
Code | Media type | Description |
---|---|---|
204 | Empty | Request successful. |
400 | Empty | If the authenticated user password does not match. |
404 | application/json | If the corresponding user cannot be found |
500 | application/json | The user could not be created due to an internal server error. See the Introduction for the error response format. |
PUT /user/jonny1/credentials
Request body:
{"password":"s3cr3t", "authenticatedUserPassword": "demo"}
None.
Updates the profile information of an already existing user.
PUT /user/{id}/profile
Name | Type | Description |
---|---|---|
id | String | The id of the user. |
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. |
String | The email of the user. |
Empty.
Code | Media type | Description |
---|---|---|
204 | None | Request successful. |
404 | application/json | If the user with the requested Id cannot be found. |
500 | application/json | The user could not be updated due to an internal server error. See the Introduction for the error response format. |
PUT /user/jonny1/profile
Request body:
{"id":"jonny1",
"firstName":"John",
"lastName":"Doe",
"email":"aNewEmailAddress"}
Empty.
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.
GET /variable-instance
Name | Description |
---|---|
variableName | Filter by variable instance name. |
variableNameLike | Filter by the variable instance name. The parameter can include the wildcard % to express like-strategy such as: starts with (% name), ends with (name% ) or contains (% name% ). |
processInstanceIdIn | Only include variable instances which belongs to one of the passed and comma-separated process instance ids. |
executionIdIn | Only include variable instances which belongs to one of the passed and comma-separated execution ids. |
taskIdIn | Only include variable instances which belongs to one of the passed and comma-separated task ids. |
activityInstanceIdIn | Only include variable instances which belongs to one of the passed and comma-separated activity instance ids. |
variableValues | Only include variable instances that have the certain values.
Value filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
sortBy | Sort the results lexicographically by a given criterion. Valid values are
variableName , variableType and activityInstanceId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
A json array of variable instance objects. Each variable instance object has the following properties:
Name | Value | Description |
---|---|---|
name | String | The name of the variable instance. |
type | String | The simple class name of the variable instance. |
value | String/Number/Boolean/Object | Object serialization uses Jackson's POJO/bean property introspection feature. |
processInstanceId | String | The id of the process instance that this variable instance belongs to. |
executionId | String | The id of the execution that this variable instance belongs to. |
taskId | String | The id of the task that this variable instance belongs to. |
activityInstanceId | String | The id of the activity instance that this variable instance belongs to. |
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. |
GET /variable-instance?processInstanceIdIn=aProcessInstanceId,anotherProcessInstanceId&variableValues=amount_gteq_5,amount_lteq_200
[
{
"name": "amount",
"type": "integer",
"value": 5,
"processInstanceId": "aProcessInstanceId",
"executionId": "b68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726"
},
{
"name": "amount",
"type": "integer",
"value": 15,
"processInstanceId": "aProcessInstanceId",
"executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726"
},
{
"name": "amount",
"type": "integer",
"value": 150,
"processInstanceId": "anotherProcessInstanceId",
"executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"activityInstanceId": "Task_2:b68b71ca-e310-11e2-beb0-f0def1557726"
}
]
Query for the number of variable instances that fulfill given parameters. Takes the same parameters as the get variable instances method.
GET /variable-instance/count
Name | Description |
---|---|
variableName | Filter by variable instance name. |
variableNameLike | Filter by the variable instance name. The parameter can include the wildcard % to express like-strategy such as: starts with (% name), ends with (name% ) or contains (% name% ). |
processInstanceIdIn | Only include variable instances which belongs to one of the passed and comma-separated process instance ids. |
executionIdIn | Only include variable instances which belongs to one of the passed and comma-separated execution ids. |
taskIdIn | Only include variable instances which belongs to one of the passed and comma-separated task ids. |
activityInstanceIdIn | Only include variable instances which belongs to one of the passed and comma-separated activity instance ids. |
variableValues | Only include variable instances that have the certain values.
Value filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value .
key is the variable name, op is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like .key and value may not contain underscore or comma characters.
|
sortBy | Sort the results lexicographically by a given criterion. Valid values are
variableName , variableType and activityInstanceId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
firstResult | Pagination of results. Specifies the index of the first result to return. |
maxResults | Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left. |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching variable instances. |
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. |
GET /variable-instance/count?processInstanceIdIn=aProcessInstanceId,anotherProcessInstanceId&variableValues=amount_gteq_5,amount_lteq_200
{"count": 3}
Query for variable instances that fulfill given parameters through a json object. This method is slightly more powerful than the
GET query, because it allows to filter by multiple variable instances of types String
, Number
or Boolean
.
POST /variable-instance
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. |
A json object with the following properties:
Name | Description |
---|---|
variableName | Filter by variable instance name. |
variableNameLike | Filter by the variable instance name. The parameter can include the wildcard % to express like-strategy such as: starts with (% name), ends with (name% ) or contains (% name% ). |
processInstanceIdIn | Only include variable instances which belongs to one of the passed process instance ids. |
executionIdIn | Only include variable instances which belongs to one of the passed execution ids. |
taskIdIn | Only include variable instances which belongs to one of the passed task ids. |
activityInstanceIdIn | Only include variable instances which belongs to one of the passed activity instance ids. |
variableValues | A json array to only include variable instances that have the certain values. The array consists of objects with the three properties name , operator and value .
name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.value may be String , Number or Boolean .
Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
variableName , variableType and activityInstanceId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json array of variable instance objects. Each variable instance object has the following properties:
Name | Value | Description |
---|---|---|
name | String | The name of the variable instance. |
type | String | The simple class name of the variable instance. |
value | String/Number/Boolean/Object | Object serialization uses Jackson's POJO/bean property introspection feature. |
processInstanceId | String | The id of the process instance that this variable instance belongs to. |
executionId | String | The id of the execution that this variable instance belongs to. |
taskId | String | The id of the task that this variable instance belongs to. |
activityInstanceId | String | The id of the activity instance that this variable instance belongs to. |
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. |
POST /variable-instance
Request body:
{"variableValuess":
[{"name": "amount",
"operator": "gteq",
"value": "5"
},
{"name": "amount",
"operator": "lteq",
"value": 200}],
"processInstanceIdIn": [ "aProcessInstanceId", "anotherProcessInstanceId" ]}
[
{
"name": "amount",
"type": "integer",
"value": 5,
"processInstanceId": "aProcessInstanceId",
"executionId": "b68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726"
},
{
"name": "amount",
"type": "integer",
"value": 15,
"processInstanceId": "aProcessInstanceId",
"executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726"
},
{
"name": "amount",
"type": "integer",
"value": 150,
"processInstanceId": "anotherProcessInstanceId",
"executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"activityInstanceId": "Task_2:b68b71ca-e310-11e2-beb0-f0def1557726"
}
]
Query for the number of variable instances that fulfill given parameters. This method takes the same message body as the POST query and is thus slightly more powerful than the GET query count.
POST /variable-instance/count
A json object with the following properties:
Name | Description |
---|---|
variableName | Filter by variable instance name. |
variableNameLike | Filter by the variable instance name. The parameter can include the wildcard % to express like-strategy such as: starts with (% name), ends with (name% ) or contains (% name% ). |
processInstanceIdIn | Only include variable instances which belongs to one of the passed process instance ids. |
executionIdIn | Only include variable instances which belongs to one of the passed execution ids. |
taskIdIn | Only include variable instances which belongs to one of the passed task ids. |
activityInstanceIdIn | Only include variable instances which belongs to one of the passed activity instance ids. |
variableValues | A json array to only include variable instances that have the certain values. The array consists of objects with the three properties name , operator and value .
name (String) is the variable name, operator (String) is the comparison operator to be used and value the variable value.value may be String , Number or Boolean .
Valid operator values are: eq - equals; neq - not equals; gt - greater than;
gteq - greater than or equals; lt - lower than; lteq - lower than or equals;
like . |
sortBy | Sort the results lexicographically by a given criterion. Valid values are
variableName , variableType and activityInstanceId .
Must be used in conjunction with the sortOrder parameter. |
sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
A json object that contains the count as the only property.
Name | Value | Description |
---|---|---|
count | Number | The number of matching variable instances. |
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. |
POST /variable-instance/count
Request body:
{"variableValuess":
[{"name": "amount",
"operator": "gteq",
"value": "5"
},
{"name": "amount",
"operator": "lteq",
"value": 200}],
"processInstanceIdIn": [ "aProcessInstanceId", "anotherProcessInstanceId" ]}
{"count": 3}