Camunda Platform REST API (7.22.0-ee)

Download OpenAPI specification:Download

OpenApi Spec for Camunda Platform REST API.

Authorization

Get Authorizations

Queries for a list of authorizations using a list of parameters. The size of the result set can be retrieved by using the Get Authorization Count method.

Authorizations:

basicAuth

query Parameters

id	string Filter by the id of the authorization.
type	integer <int32> Filter by authorization type. (0=global, 1=grant, 2=revoke). See the User Guide for more information about authorization types.
userIdIn	string Filter by a comma-separated list of userIds.
groupIdIn	string Filter by a comma-separated list of groupIds.
resourceType	integer <int32> Filter by an integer representation of the resource type. See the User Guide for a list of integer representations of resource types.
resourceId	string Filter by resource id.
sortBy	string Enum: "resourceType" "resourceId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /authorization?userIdIn=jonny1,jonny2

[{"id": "anAuthorizationId",
"type": 0,
"permissions": ["ALL"
],
"userId": "jonny1",
"groupId": null,
"resourceType": 1,
"resourceId": "*"
},
{"id": "anotherAuthorizationId",
"type": 0,
"permissions": ["CREATE",
"READ"
],
"userId": "jonny2",
"groupId": null,
"resourceType": 1,
"resourceId": "*",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "f8259e5d-ab9d-11e8-8449-e4a7a094a9d6"
}
]

Authorization Resource Options

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

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

OPTIONS /authorization

{"links": [{"method": "GET",
"href": "http://localhost:8080/engine-rest/authorization",
"rel": "list"
},
{"method": "GET",
"href": "http://localhost:8080/engine-rest/authorization/count",
"rel": "count"
},
{"method": "POST",
"href": "http://localhost:8080/engine-rest/authorization/create",
"rel": "create"
}
]
}

Perform an Authorization Check

Performs an authorization check for the currently authenticated user.

Authorizations:

basicAuth

query Parameters

permissionName required	string String value representing the permission name to check for.
resourceName required	string String value for the name of the resource to check permissions for.
resourceType required	integer <int32> An integer representing the resource type to check permissions for. See the User Guide for a list of integer representations of resource types.
resourceId	string The id of the resource to check permissions for. If left blank, a check for global permissions on the resource is performed.
userId	string The id of the user to check permissions for. The currently authenticated user must have a READ permission for the Authorization resource. If `userId` is blank, a check for the currently authenticated user is performed.

Responses

Response samples

200
400
401
403
404

Content type

application/json

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

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

Get Authorization Count

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

Authorizations:

basicAuth

query Parameters

id	string Filter by the id of the authorization.
type	integer <int32> Filter by authorization type. (0=global, 1=grant, 2=revoke). See the User Guide for more information about authorization types.
userIdIn	string Filter by a comma-separated list of userIds.
groupIdIn	string Filter by a comma-separated list of groupIds.
resourceType	integer <int32> Filter by an integer representation of the resource type. See the User Guide for a list of integer representations of resource types.
resourceId	string Filter by resource id.

Responses

Response samples

200
400

Content type

application/json

GET /authorization/count?userIdIn=jonny1,jonny2

{"count": 2
}

Create a New Authorization

Creates a new authorization.

Authorizations:

basicAuth

Request Body schema: application/json

type	integer or null <int32> The type of the authorization (0=global, 1=grant, 2=revoke). See the User Guide for more information about authorization types.
permissions	Array of strings or null An array of Strings holding the permissions provided by this authorization.
userId	string or null The id of the user this authorization has been created for. The value `*` represents a global authorization ranging over all users.
groupId	string or null The id of the group this authorization has been created for.
resourceType	integer or null <int32> An integer representing the resource type. See the User Guide for a list of integer representations of resource types.
resourceId	string or null The resource Id. The value `*` represents an authorization ranging over all instances of a resource.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400
403
500

Content type

application/json

POST /authorization/create

{"id": "anAuthorizationId",
"type": 0,
"permissions": ["CREATE",
"READ"
],
"userId": "*",
"groupId": null,
"resourceType": 1,
"resourceId": "*",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "f8259e5d-ab9d-11e8-8449-e4a7a094a9d6",
"links": [{"method": "GET",
"href"": "http://localhost:8080/engine-rest/authorization/anAuthorizationId",
"rel": "self"
},
{"method": "PUT",
"href"": "http://localhost:8080/engine-rest/authorization/anAuthorizationId",
"rel": "update"
},
{"method": "DELETE",
"href"": "http://localhost:8080/engine-rest/authorization/anAuthorizationId",
"rel": "delete"
}
]
}

Delete Authorization

Deletes an authorization by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the authorization to be deleted.

Responses

Response samples

403
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Authorization

Retrieves an authorization by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the authorization to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /authorization/anAuthorizationId

{"id": "anAuthorizationId",
"type": 0,
"permissions": ["CREATE",
"READ"
],
"userId": "*",
"groupId": null,
"resourceType": 1,
"resourceId": "*",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "f8259e5d-ab9d-11e8-8449-e4a7a094a9d6"
}

Authorization Resource Options

The OPTIONS request allows you to check for the set of available operations that the currently authenticated user can perform on a given instance of the /authorization resource. Whether the user can perform an operation or not may depend on various factors, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the authorization to be retrieved.

Responses

Response samples

200

Content type

application/json

OPTIONS /authorization/anAuthorizationId

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

Update an Authorization

Updates an authorization by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the authorization to be updated.

Request Body schema: application/json

permissions	Array of strings or null An array of Strings holding the permissions provided by this authorization.
userId	string or null The id of the user this authorization has been created for. The value `*` represents a global authorization ranging over all users.
groupId	string or null The id of the group this authorization has been created for.
resourceType	integer or null <int32> An integer representing the resource type. See the User Guide for a list of integer representations of resource types.
resourceId	string or null The resource Id. The value `*` represents an authorization ranging over all instances of a resource.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

400
403
404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Batch

Get List

Queries for batches that fulfill given parameters. Parameters may be the properties of batches, such as the id or type. The size of the result set can be retrieved by using the Get Batch Count method.

Authorizations:

basicAuth

query Parameters

sortBy	string Enum: "batchId" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
batchId	string Filter by batch id.
type	string Filter by batch type. See the User Guide for more information about batch types.
tenantIdIn	string Filter by a comma-separated list of `Strings`. A batch matches if it has one of the given tenant ids.
withoutTenantId	boolean Only include batches which belong to no tenant. Value can effectively only be `true`, as `false` is the default behavior.
suspended	boolean A `Boolean` value which indicates whether only active or suspended batches should be included. When the value is set to `true`, only suspended batches will be returned and when the value is set to `false`, only active batches will be returned.
createdBy	string Only include batches that were started by this user id.
startedBefore	string <date-time> Only include batches that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Only include batches that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
withFailures	boolean Only include batches having jobs with failures. Value can only be `true`.
withoutFailures	boolean Only include batches having jobs without failures. Value can only be `true`.

Responses

Response samples

200
400

Content type

application/json

Response for GET /batch?type=aBatchType&sortBy=batchId&sortOrder=asc

[{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"jobsCreated": 10,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"suspended": false,
"tenantId": "aTenantId",
"createUserId": "aUserId"
}
]

Get List Count

Requests the number of batches that fulfill the query criteria. Takes the same filtering parameters as the Get Batches method.

Authorizations:

basicAuth

query Parameters

batchId	string Filter by batch id.
type	string Filter by batch type. See the User Guide for more information about batch types.
tenantIdIn	string Filter by a comma-separated list of `Strings`. A batch matches if it has one of the given tenant ids.
withoutTenantId	boolean Only include batches which belong to no tenant. Value can effectively only be `true`, as `false` is the default behavior.
suspended	boolean A `Boolean` value which indicates whether only active or suspended batches should be included. When the value is set to `true`, only suspended batches will be returned and when the value is set to `false`, only active batches will be returned.
createdBy	string Only include batches that were started by this user id.
startedBefore	string <date-time> Only include batches that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Only include batches that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
withFailures	boolean Only include batches having jobs with failures. Value can only be `true`.
withoutFailures	boolean Only include batches having jobs without failures. Value can only be `true`.

Responses

Response samples

200
400

Content type

application/json

Response for GET /batch/count?type=aBatchType

{"count": 1
}

Get Statistics

Queries for batch statistics that fulfill given parameters. Parameters may be the properties of batches, such as the id or type. The size of the result set can be retrieved by using the Get Batch Statistics Count method.

Authorizations:

basicAuth

query Parameters

sortBy	string Enum: "batchId" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
batchId	string Filter by batch id.
type	string Filter by batch type. See the User Guide for more information about batch types.
tenantIdIn	string Filter by a comma-separated list of `Strings`. A batch matches if it has one of the given tenant ids.
withoutTenantId	boolean Only include batches which belong to no tenant. Value can effectively only be `true`, as `false` is the default behavior.
suspended	boolean A `Boolean` value which indicates whether only active or suspended batches should be included. When the value is set to `true`, only suspended batches will be returned and when the value is set to `false`, only active batches will be returned.
createdBy	string Only include batches that were started by this user id.
startedBefore	string <date-time> Only include batches that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Only include batches that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
withFailures	boolean Only include batches having jobs with failures. Value can only be `true`.
withoutFailures	boolean Only include batches having jobs without failures. Value can only be `true`.

Responses

Response samples

200
400

Content type

application/json

Response for GET /batch/statistics?type=aBatchType&sortBy=batchId&sortOrder=asc

[{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"jobsCreated": 10,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"remainingJobs": 3,
"completedJobs": 7,
"failedJobs": 1,
"suspended": false,
"tenantId": "aTenantId",
"createUserId": "aUserId"
}
]

Get Statistics Count

Requests the number of batch statistics that fulfill the query criteria. Takes the same filtering parameters as the Get Batch Statistics method.

Authorizations:

basicAuth

query Parameters

batchId	string Filter by batch id.
type	string Filter by batch type. See the User Guide for more information about batch types.
tenantIdIn	string Filter by a comma-separated list of `Strings`. A batch matches if it has one of the given tenant ids.
withoutTenantId	boolean Only include batches which belong to no tenant. Value can effectively only be `true`, as `false` is the default behavior.
suspended	boolean A `Boolean` value which indicates whether only active or suspended batches should be included. When the value is set to `true`, only suspended batches will be returned and when the value is set to `false`, only active batches will be returned.
createdBy	string Only include batches that were started by this user id.
startedBefore	string <date-time> Only include batches that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Only include batches that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
withFailures	boolean Only include batches having jobs with failures. Value can only be `true`.
withoutFailures	boolean Only include batches having jobs without failures. Value can only be `true`.

Responses

Response samples

200
400

Content type

application/json

Response for GET /batch/count?type=aBatchType

{"count": 1
}

Delete

Deletes a batch by id, including all related jobs and job definitions. Optionally also deletes the batch history.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the batch to be deleted.

query Parameters

cascade

boolean

true, if the historic batch and historic job logs for this batch should also be deleted.

Responses

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get

Retrieves a batch by id, according to the Batch interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the batch to be retrieved.

Responses

Response samples

200
404

Content type

application/json

Response for GET /batch/aBatchId

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"jobsCreated": 10,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"suspended": false,
"tenantId": "aTenantId",
"createUserId": "aUserId"
}

Activate/Suspend

Activates or suspends a batch by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the batch to activate or suspend.

Request Body schema: application/json

suspended

boolean or null

A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, job definition, or batch). When the value is set to true, the given instance will be suspended and when the value is set to false, the given instance will be activated.

Responses

Request samples

Payload

Content type

application/json

{"suspended": true
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Condition

Evaluate

Triggers evaluation of conditions for conditional start event(s). Internally this maps to the engines condition evaluation builder method ConditionEvaluationBuilder#evaluateStartConditions(). For more information see the Conditional Start Events section of the BPMN 2.0 Implementation Reference.

Authorizations:

basicAuth

Request Body schema: application/json

	object or null A map of variables which are used for evaluation of the conditions and are injected into the process instances which have been triggered. Each key is a variable name and each value a JSON variable value object with the following properties.
businessKey	string or null Used for the process instances that have been triggered after the evaluation.
tenantId	string or null Used to evaluate a condition for a tenant with the given id. Will only evaluate conditions of process definitions which belong to the tenant.
withoutTenantId	boolean or null A Boolean value that indicates whether the conditions should only be evaluated of process definitions which belong to no tenant or not. Value may only be true, as false is the default behavior.
processDefinitionId	string or null Used to evaluate conditions of the process definition with the given id.

Responses

Request samples

Payload

Content type

application/json

The content of the Request Body

{"variables": {"temperature": {"value": 24,
"type": "Integer",
"valueInfo": {"transient": true
}
},
"city": {"value": "Parma",
"type": "String"
}
},
"businessKey": "aBusinessKey",
"tenantId": "aTenantId"
}

Response samples

200
400
403

Content type

application/json

The Response content of a status 200

[{"links": [ ],
"id": "aProcInstId",
"definitionId": "aProcDefId",
"businessKey": "aBusinessKey",
"caseInstanceId": null,
"ended": false,
"suspended": false,
"tenantId": "aTenantId"
},
{"links": [ ],
"id": "anotherId",
"definitionId": "aProcDefId",
"businessKey": "aBusinessKey",
"caseInstanceId": null,
"ended": false,
"suspended": false,
"tenantId": "aTenantId"
}
]

Decision Definition

Get List

Queries for decision definitions that fulfill given parameters. Parameters may be the properties of decision definitions, such as the name, key or version. The size of the result set can be retrieved by using the Get Decision Definition Count method.

Authorizations:

basicAuth

query Parameters

sortBy	string Enum: "category" "decisionRequirementsDefinitionKey" "key" "id" "name" "version" "deploymentId" "deployTime" "versionTag" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
decisionDefinitionId	string Filter by decision definition id.
decisionDefinitionIdIn	string Filter by decision definition ids.
name	string Filter by decision definition name.
nameLike	string Filter by decision definition names that the parameter is a substring of.
deploymentId	string Filter by the deployment the id belongs to.
deployedAfter	string <date-time> Filter by the deploy time of the deployment the decision definition belongs to. Only selects decision definitions that have been deployed after (exclusive) a specific time.
deployedAt	string <date-time> Filter by the deploy time of the deployment the decision definition belongs to. Only selects decision definitions that have been deployed at a specific time (exact match).
key	string Filter by decision definition key, i.e., the id in the DMN 1.0 XML. Exact match.
keyLike	string Filter by decision definition keys that the parameter is a substring of.
category	string Filter by decision definition category. Exact match.
categoryLike	string Filter by decision definition categories that the parameter is a substring of.
version	integer <int32> Filter by decision definition version.
latestVersion	boolean Only include those decision definitions that are latest versions. Value may only be `true`, as `false` is the default behavior.
resourceName	string Filter by the name of the decision definition resource. Exact match.
resourceNameLike	string Filter by names of those decision definition resources that the parameter is a substring of.
decisionRequirementsDefinitionId	string Filter by the id of the decision requirements definition this decision definition belongs to.
decisionRequirementsDefinitionKey	string Filter by the key of the decision requirements definition this decision definition belongs to.
withoutDecisionRequirementsDefinition	boolean Only include decision definitions which does not belongs to any decision requirements definition. Value may only be `true`, as `false` is the default behavior.
tenantIdIn	string Filter by a comma-separated list of `Strings`. A decision definition must have one of the given tenant ids.
withoutTenantId	boolean Only include decision definitions which belong to no tenant. Value can effectively only be `true`, as `false` is the default behavior.
includeDecisionDefinitionsWithoutTenantId	boolean Include decision definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
versionTag	string Filter by the version tag.
versionTagLike	string Filter by the version tags of those decision definition resources that the parameter is a substring of.

Responses

Response samples

200
400

Content type

application/json

Response for GET /decision-definition?key=dish-decision&sortBy=category&sortOrder=asc

[{"id": "dish-decision:1:c633e8a8-41b7-11e6-b0ef-00aa004d0001",
"key": "dish-decision",
"category": "http://camunda.org/schema/1.0/dmn",
"name": "Dish Decision",
"version": 1,
"resource": "drd-dish-decision.dmn",
"deploymentId": "c627175e-41b7-11e6-b0ef-00aa004d0001",
"decisionRequirementsDefinitionId": "dish:1:c633c195-41b7-11e6-b0ef-00aa004d0001",
"decisionRequirementsDefinitionKey": "dish",
"tenantId": null,
"versionTag": null,
"historyTimeToLive": 5
}
]

Get List Count

Requests the number of decision definitions that fulfill the query criteria. Takes the same filtering parameters as the Get Decision Definition method.

Authorizations:

basicAuth

query Parameters

decisionDefinitionId	string Filter by decision definition id.
decisionDefinitionIdIn	string Filter by decision definition ids.
name	string Filter by decision definition name.
nameLike	string Filter by decision definition names that the parameter is a substring of.
deploymentId	string Filter by the deployment the id belongs to.
deployedAfter	string <date-time> Filter by the deploy time of the deployment the decision definition belongs to. Only selects decision definitions that have been deployed after (exclusive) a specific time.
deployedAt	string <date-time> Filter by the deploy time of the deployment the decision definition belongs to. Only selects decision definitions that have been deployed at a specific time (exact match).
key	string Filter by decision definition key, i.e., the id in the DMN 1.0 XML. Exact match.
keyLike	string Filter by decision definition keys that the parameter is a substring of.
category	string Filter by decision definition category. Exact match.
categoryLike	string Filter by decision definition categories that the parameter is a substring of.
version	integer <int32> Filter by decision definition version.
latestVersion	boolean Only include those decision definitions that are latest versions. Value may only be `true`, as `false` is the default behavior.
resourceName	string Filter by the name of the decision definition resource. Exact match.
resourceNameLike	string Filter by names of those decision definition resources that the parameter is a substring of.
decisionRequirementsDefinitionId	string Filter by the id of the decision requirements definition this decision definition belongs to.
decisionRequirementsDefinitionKey	string Filter by the key of the decision requirements definition this decision definition belongs to.
withoutDecisionRequirementsDefinition	boolean Only include decision definitions which does not belongs to any decision requirements definition. Value may only be `true`, as `false` is the default behavior.
tenantIdIn	string Filter by a comma-separated list of `Strings`. A decision definition must have one of the given tenant ids.
withoutTenantId	boolean Only include decision definitions which belong to no tenant. Value can effectively only be `true`, as `false` is the default behavior.
includeDecisionDefinitionsWithoutTenantId	boolean Include decision definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
versionTag	string Filter by the version tag.
versionTagLike	string Filter by the version tags of those decision definition resources that the parameter is a substring of.

Responses

Response samples

200
400

Content type

application/json

Response for GET /decision-definition/count?key=dish-decision&version=2

{"count": 1
}

Get Decision Definition By Key

Retrieves the latest version of the decision definition which belongs to no tenant.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the decision definition (the latest version thereof) to be retrieved.

Responses

Response samples

200
404

Content type

application/json

Response for GET /decision-definition/key/dish-decision

{"id": "aDecisionDefinitionId",
"key": "dish-decision",
"category": "http://camunda.org/schema/1.0/dmn",
"name": "Dish Decision",
"version": 1,
"resource": "drd-dish-decision.dmn",
"deploymentId": "c627175e-41b7-11e6-b0ef-00aa004d0001",
"decisionRequirementsDefinitionId": "dish:1:c633c195-41b7-11e6-b0ef-00aa004d0001",
"decisionRequirementsDefinitionKey": "dish",
"tenantId": null,
"versionTag": null,
"historyTimeToLive": 5
}

Get Diagram By Key

Returns the diagram for the latest version of the decision definition which belongs to no tenant

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the decision definition (the latest version thereof) to be retrieved.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Evaluate By Key

Evaluates the latest version of the decision definition which belongs to no tenant. The input values of the decision have to be supplied in the request body.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the decision definition (the latest version thereof) to be evaluated.

Request Body schema: application/json

object or null

Responses

Request samples

Payload

Content type

application/json

{"variables": {"amount": {"value": 600,
"type": "Double"
},
"invoiceCategory": {"value": "Misc",
"type": "String"
}
}
}

Response samples

200
404

Content type

application/json

Response for POST /decision-definition/key/aKey/evaluate

[{"result": {"value": "management",
"type": "String",
"valueInfo": null
}
}
]

Update History Time to Live By Key

Updates the latest version of the decision definition which belongs to no tenant. The field is used within History cleanup.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the decision definitions to change history time to live.

Request Body schema: application/json

historyTimeToLive

integer or null <int32> >= 0

New value for historyTimeToLive field of the definition. Can be null if enforceHistoryTimeToLive is configured to false. Cannot be negative.

Responses

Request samples

Payload

Content type

application/json

{"historyTimeToLive": 5
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Decision Definition By Key And Tenant Id

Retrieves the latest version of the decision definition for tenant

Authorizations:

basicAuth

path Parameters

key required	string The key of the decision definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant the decision definition belongs to.

Responses

Response samples

200
404

Content type

application/json

Response for GET /decision-definition/key/dish-decision/tenant-id/aTenantId

{"id": "aDecisionDefinitionId",
"key": "dish-decision",
"category": "http://camunda.org/schema/1.0/dmn",
"name": "Dish Decision",
"version": 1,
"resource": "drd-dish-decision.dmn",
"deploymentId": "c627175e-41b7-11e6-b0ef-00aa004d0001",
"decisionRequirementsDefinitionId": "dish:1:c633c195-41b7-11e6-b0ef-00aa004d0001",
"decisionRequirementsDefinitionKey": "dish",
"tenantId": "aTenantId",
"versionTag": null,
"historyTimeToLive": 5
}

Get Diagram By Key And Tenant

Returns the XML of the latest version of the decision definition for tenant.

Authorizations:

basicAuth

path Parameters

key required	string The key of the decision definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant the decision definition belongs to.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Evaluate By Key And Tenant

Evaluates the latest version of the decision definition for tenant. The input values of the decision have to be supplied in the request body.

Authorizations:

basicAuth

path Parameters

key required	string The key of the decision definition (the latest version thereof) to be evaluated.
tenant-id required	string The id of the tenant the decision definition belongs to.

Request Body schema: application/json

object or null

Responses

Request samples

Payload

Content type

application/json

{"variables": {"amount": {"value": 600,
"type": "Double"
},
"invoiceCategory": {"value": "Misc",
"type": "String"
}
}
}

Response samples

200
404

Content type

application/json

Response for POST /decision-definition/akey/aKey/tenand-id/aTenantId/evaluate

[{"result": {"value": "management",
"type": "String",
"valueInfo": null
}
}
]

Update History Time to Live By Key And Tenant

Updates the latest version of the decision definition for tenant. The field is used within History cleanup. The value of the update is mandatory by default and does not allow null values. To enable them, please set the feature flag enforceHistoryTimeToLive to false. Read more in [Configuration Properties] (https://docs.camunda.org/manual/7.22/reference/deployment-descriptors/tags/process-engine#configuration-properties)

Authorizations:

basicAuth

path Parameters

key required	string The key of the decision definitions to change history time to live.
tenant-id required	string The id of the tenant the decision definition belongs to.

Request Body schema: application/json

historyTimeToLive

integer or null <int32> >= 0

New value for historyTimeToLive field of the definition. Can be null if enforceHistoryTimeToLive is configured to false. Cannot be negative.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/decision-definition/key/{key}/tenant-id/{tenant-id}/history-time-to-live

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/decision-definition/key/{key}/tenant-id/{tenant-id}/history-time-to-live

The API server with a custom url

/{url}/decision-definition/key/{key}/tenant-id/{tenant-id}/history-time-to-live

Request samples

Payload

Content type

application/json

{"historyTimeToLive": 5
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get XML By Key and Tenant

Retrieves the XML of the latest version of the decision definition for tenant

Authorizations:

basicAuth

path Parameters

key required	string The key of the decision definition (the latest version thereof).
tenant-id required	string The id of the tenant the decision definition belongs to.

Responses

Response samples

200
404

Content type

application/json

Response for GET /decision-definition/key/aKey/tenant-id/aTenantId/xml

{"id": "aDecisionDefinitionId",
"dmnXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n                                    <definitions xmlns=\"http://www.omg.org/spec/DMN/20151101/dmn.xsd\"\n                                                 id=\"definitions\"\n                                                 name=\"camunda\"\n                                                 namespace=\"http://camunda.org/schema/1.0/dmn\">\n                                      <decision id=\"testDecision\" name=\"decision\">\n                                        <decisionTable id=\"table\">\n                                          <output id=\"result\" name=\"result\" >\n                                          </output>\n                                          <rule id=\"rule\">\n                                            <outputEntry id=\"output1\">\n                                              <text>\"not okay\"</text>\n                                            </outputEntry>\n                                          </rule>\n                                        </decisionTable>\n                                      </decision>\n                                    </definitions>"
}

Get XML By Key

Retrieves the XML for the latest version of the decision definition which belongs to no tenant.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the decision definition (the latest version thereof).

Responses

Response samples

200
404

Content type

application/json

Response for GET /decision-definition/key/aKey/xml

{"id": "aDecisionDefinitionId",
"dmnXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n                                    <definitions xmlns=\"http://www.omg.org/spec/DMN/20151101/dmn.xsd\"\n                                                 id=\"definitions\"\n                                                 name=\"camunda\"\n                                                 namespace=\"http://camunda.org/schema/1.0/dmn\">\n                                      <decision id=\"testDecision\" name=\"decision\">\n                                        <decisionTable id=\"table\">\n                                          <output id=\"result\" name=\"result\" >\n                                          </output>\n                                          <rule id=\"rule\">\n                                            <outputEntry id=\"output1\">\n                                              <text>\"not okay\"</text>\n                                            </outputEntry>\n                                          </rule>\n                                        </decisionTable>\n                                      </decision>\n                                    </definitions>"
}

Get Decision Definition By Id

Retrieves a decision definition by id, according to the DecisionDefinition interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the decision definition to be retrieved.

Responses

Response samples

200
404

Content type

application/json

Response for GET /decision-definition/aDecisionDefinitionId

{"id": "aDecisionDefinitionId",
"key": "dish-decision",
"category": "http://camunda.org/schema/1.0/dmn",
"name": "Dish Decision",
"version": 1,
"resource": "drd-dish-decision.dmn",
"deploymentId": "c627175e-41b7-11e6-b0ef-00aa004d0001",
"decisionRequirementsDefinitionId": "dish:1:c633c195-41b7-11e6-b0ef-00aa004d0001",
"decisionRequirementsDefinitionKey": "dish",
"tenantId": null,
"versionTag": null,
"historyTimeToLive": 5
}

Get Diagram

Retrieves the diagram of a decision definition.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Evaluate By Id

Evaluates a given decision and returns the result. The input values of the decision have to be supplied in the request body.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the decision definition to be evaluated.

Request Body schema: application/json

object or null

Responses

Request samples

Payload

Content type

application/json

{"variables": {"amount": {"value": 600,
"type": "Double"
},
"invoiceCategory": {"value": "Misc",
"type": "String"
}
}
}

Response samples

200
404

Content type

application/json

Response for POST /decision-definition/aDecisionDefinitionId/evaluate

[{"result": {"value": "management",
"type": "String",
"valueInfo": null
}
}
]

Update History Time to Live

Updates history time to live for decision definition. The field is used within History cleanup.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the decision definition to change history time to live.

Request Body schema: application/json

historyTimeToLive

integer or null <int32> >= 0

New value for historyTimeToLive field of the definition. Can be null if enforceHistoryTimeToLive is configured to false. Cannot be negative.

Responses

Request samples

Payload

Content type

application/json

{"historyTimeToLive": 5
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get XML By Id

Retrieves the DMN XML of a decision definition.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the decision definition.

Responses

Response samples

200
404

Content type

application/json

Response for GET /decision-definition/aDecisionDefinitionId/xml

{"id": "aDecisionDefinitionId",
"dmnXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n                                    <definitions xmlns=\"http://www.omg.org/spec/DMN/20151101/dmn.xsd\"\n                                                 id=\"definitions\"\n                                                 name=\"camunda\"\n                                                 namespace=\"http://camunda.org/schema/1.0/dmn\">\n                                      <decision id=\"testDecision\" name=\"decision\">\n                                        <decisionTable id=\"table\">\n                                          <output id=\"result\" name=\"result\" >\n                                          </output>\n                                          <rule id=\"rule\">\n                                            <outputEntry id=\"output1\">\n                                              <text>\"not okay\"</text>\n                                            </outputEntry>\n                                          </rule>\n                                        </decisionTable>\n                                      </decision>\n                                    </definitions>"
}

Decision Requirements Definition

Get Decision Requirements Definitions

Queries for decision requirements definitions that fulfill given parameters. Parameters may be the properties of decision requirements definitions, such as the name, key or version. The size of the result set can be retrieved by using the Get Decision Requirements Definition Count method.

Authorizations:

basicAuth

query Parameters

decisionRequirementsDefinitionId	string Filter by decision requirements definition id.
decisionRequirementsDefinitionIdIn	string Filter by decision requirements definition ids.
name	string Filter by decision requirements definition name.
nameLike	string Filter by decision requirements definition names that the parameter is a substring of.
deploymentId	string Filter by the id of the deployment a decision requirement definition belongs to.
key	string Filter by decision requirements definition key, i.e., the id in the DMN 1.3 XML. Exact match.
keyLike	string Filter by decision requirements definition keys that the parameter is a substring of.
category	string Filter by decision requirements definition category. Exact match.
categoryLike	string Filter by decision requirements definition categories that the parameter is a substring of.
version	integer <int32> Filter by decision requirements definition version.
latestVersion	boolean Only include those decision requirements definitions that are latest versions. Value may only be `true`, as `false` is the default behavior.
resourceName	string Filter by the name of the decision requirements definition resource. Exact match.
resourceNameLike	string Filter by names of those decision requirements definition resources that the parameter is a substring of.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A decision requirements definition must have one of the given tenant ids.
withoutTenantId	boolean Only include decision requirements definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeDecisionRequirementsDefinitionsWithoutTenantId	boolean Include decision requirements definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "id" "key" "name" "version" "deploymentId" "category" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /decision-requirements-definition?key=dish&sortBy=version&sortOrder=asc

[{"id": "dish:1:c633c195-41b7-11e6-b0ef-00aa004d0001",
"key": "dish",
"category": "drd-test",
"name": "Dish",
"version": 1,
"resource": "dish.dmn",
"deploymentId": "c627175e-41b7-11e6-b0ef-00aa004d0001",
"tenantId": null
}
]

Get Decision Requirements Definition Count

Requests the number of decision requirements definitions that fulfill the query criteria. Takes the same filtering parameters as the Get Decision Requirements Definitions method.

Authorizations:

basicAuth

query Parameters

decisionRequirementsDefinitionId	string Filter by decision requirements definition id.
decisionRequirementsDefinitionIdIn	string Filter by decision requirements definition ids.
name	string Filter by decision requirements definition name.
nameLike	string Filter by decision requirements definition names that the parameter is a substring of.
deploymentId	string Filter by the id of the deployment a decision requirement definition belongs to.
key	string Filter by decision requirements definition key, i.e., the id in the DMN 1.3 XML. Exact match.
keyLike	string Filter by decision requirements definition keys that the parameter is a substring of.
category	string Filter by decision requirements definition category. Exact match.
categoryLike	string Filter by decision requirements definition categories that the parameter is a substring of.
version	integer <int32> Filter by decision requirements definition version.
latestVersion	boolean Only include those decision requirements definitions that are latest versions. Value may only be `true`, as `false` is the default behavior.
resourceName	string Filter by the name of the decision requirements definition resource. Exact match.
resourceNameLike	string Filter by names of those decision requirements definition resources that the parameter is a substring of.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A decision requirements definition must have one of the given tenant ids.
withoutTenantId	boolean Only include decision requirements definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeDecisionRequirementsDefinitionsWithoutTenantId	boolean Include decision requirements definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

GET /decision-requirements-definition/count?key=dish

{"count": 1
}

Get Decision Requirements Definition by Key

Retrieves a decision requirements definition according to the DecisionRequirementsDefinition interface in the engine. Returns the latest version of the decision requirements definition which belongs to no tenant.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the decision requirements definition (the latest version thereof) to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /decision-requirements-definition/key/invoiceKey

{"id": "invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c",
"key": "invoiceKey",
"category": "invoice",
"name": "receiptInvoice",
"version": 2,
"resource": "invoice.dmn",
"deploymentId": "c627175e-41b7-11e6-b0ef-00aa004d0001",
"tenantId": null
}

Get Decision Requirements Diagram by Key

Retrieves the diagram of a decision requirements definition. Returns the diagram for the latest version of the decision requirements definition which belongs to no tenant.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the decision requirements definition (the latest version thereof) to be retrieved.

Responses

Response samples

200
404

Content type

image/*

GET /decision-requirements-definition/key/invoiceKey/diagram

Get Decision Requirements Definition by Key and Tenant ID

Retrieves a decision requirements definition according to the DecisionRequirementsDefinition interface in the engine. Returns the latest version of the decision requirements definition for a tenant.

Authorizations:

basicAuth

path Parameters

key required	string The key of the decision requirements definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant to which the decision requirements definition belongs to.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}

The API server with a custom url

/{url}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}

Response samples

200
404

Content type

application/json

GET /decision-requirements-definition/key/invoiceKey/tenant-id/tenantA

{"id": "invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c",
"key": "invoiceKey",
"category": "invoice",
"name": "receiptInvoice",
"version": 2,
"resource": "invoice.dmn",
"deploymentId": "c627175e-41b7-11e6-b0ef-00aa004d0001",
"tenantId": "tenantA"
}

Get Decision Requirements Diagram by Key and Tenant ID

Retrieves the diagram of a decision requirements definition. Returns the diagram of the latest version of the decision requirements definition for a tenant.

Authorizations:

basicAuth

path Parameters

key required	string The key of the decision requirements definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant to which the decision requirements definition belongs to.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}/diagram

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}/diagram

The API server with a custom url

/{url}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}/diagram

Response samples

200
404

Content type

image/*

GET /decision-requirements-definition/key/invoiceKey/tenant-id/tenantA/diagram

Get DMN XML by Key and Tenant ID

Retrieves the DMN XML of a decision requirements definition. Returns the XML of the latest version of the decision requirements definition for a tenant.

Authorizations:

basicAuth

path Parameters

key required	string The key of the decision requirements definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant to which the decision requirements definition belongs to.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}/xml

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}/xml

The API server with a custom url

/{url}/decision-requirements-definition/key/{key}/tenant-id/{tenant-id}/xml

Response samples

200
404

Content type

application/json

GET /decision-requirements-definition/key/invoiceKey/tenant-id/tenantA/xml

{"id": "invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c",
"dmnXml": "<?xml version=\"1.1\" encoding=\"UTF-8\"?>...<definitions id=\"dish\" name=\"Dish\" namespace=\"test-drg\" ... />"
}

Get DMN XML by Key

Retrieves the DMN XML of a decision requirements definition. Returns the XML for the latest version of the decision requirements definition which belongs to no tenant.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the decision requirements definition (the latest version thereof) to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /decision-requirements-definition/key/invoiceKey/xml

{"id": "invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c",
"dmnXml": "<?xml version=\"1.1\" encoding=\"UTF-8\"?>...<definitions id=\"dish\" name=\"Dish\" namespace=\"test-drg\" ... />"
}

Get Decision Requirements Definition by ID

Retrieves a decision requirements definition according to the DecisionRequirementsDefinition interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the decision requirements definition to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /decision-requirements-definition/invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c

{"id": "invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c",
"key": "invoiceKey",
"category": "invoice",
"name": "receiptInvoice",
"version": 2,
"resource": "invoice.dmn",
"deploymentId": "c627175e-41b7-11e6-b0ef-00aa004d0001",
"tenantId": null
}

Get Decision Requirements Diagram by ID

Retrieves the diagram of a decision requirements definition.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the decision requirements definition.

Responses

Response samples

200
404

Content type

image/*

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

Get DMN XML by ID

Retrieves the DMN XML of a decision requirements definition.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the decision requirements definition.

Responses

Response samples

200
404

Content type

application/json

GET /decision-requirements-definition/invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c/xml

{"id": "invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c",
"dmnXml": "<?xml version=\"1.1\" encoding=\"UTF-8\"?>...<definitions id=\"dish\" name=\"Dish\" namespace=\"test-drg\" ... />"
}

Deployment

Get List

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

Authorizations:

basicAuth

query Parameters

id	string Filter by deployment id
name	string Filter by the deployment name. Exact match.
nameLike	string Filter by the deployment name that the parameter is a substring of. The parameter can include the wildcard `%` to express like-strategy such as: starts with (`%`name), ends with (name`%`) or contains (`%`name`%`).
source	string Filter by the deployment source.
withoutSource	boolean Default: false Filter by the deployment source whereby source is equal to `null`.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A deployment must have one of the given tenant ids.
withoutTenantId	boolean Default: false Only include deployments which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeDeploymentsWithoutTenantId	boolean Default: false Include deployments which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
after	string <date-time> Restricts to all deployments after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
before	string <date-time> Restricts to all deployments before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
sortBy	string Enum: "id" "name" "deploymentTime" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

[{"id": "someId",
"name": "deploymentName",
"source": "process application",
"tenantId": null,
"deploymentTime": "2013-04-23T13:42:43.000+0200"
}
]

Get List Count

Queries for the number of deployments that fulfill given parameters. Takes the same parameters as the Get Deployments method.

Authorizations:

basicAuth

query Parameters

id	string Filter by deployment id
name	string Filter by the deployment name. Exact match.
nameLike	string Filter by the deployment name that the parameter is a substring of. The parameter can include the wildcard `%` to express like-strategy such as: starts with (`%`name), ends with (name`%`) or contains (`%`name`%`).
source	string Filter by the deployment source.
withoutSource	boolean Default: false Filter by the deployment source whereby source is equal to `null`.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A deployment must have one of the given tenant ids.
withoutTenantId	boolean Default: false Only include deployments which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeDeploymentsWithoutTenantId	boolean Default: false Include deployments which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
after	string <date-time> Restricts to all deployments after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
before	string <date-time> Restricts to all deployments before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.

Responses

Response samples

200
400

Content type

application/json

{"count": 1
}

Create

Creates a deployment.

Security Consideration

Deployments can contain custom code in form of scripts or EL expressions to customize process behavior. This may be abused for remote execution of arbitrary code.

Authorizations:

basicAuth

Request Body schema: multipart/form-data

tenant-id	string or null The tenant id for the deployment to be created.
deployment-source	string or null The source for the deployment to be created.
deploy-changed-only	boolean or null Default: false A flag indicating whether the process engine should perform duplicate checking on a per-resource basis. If set to true, only those resources that have actually changed are deployed. Checks are made against resources included previous deployments of the same name and source and only against the latest versions of those resources. If set to true, the option enable-duplicate-filtering is overridden and set to true.
enable-duplicate-filtering	boolean or null Default: false A flag indicating whether the process engine should perform duplicate checking for the deployment or not. This allows you to check if a deployment with the same name and the same resouces already exists and if true, not create a new deployment but instead return the existing deployment. The default value is false.
deployment-name	string or null The name for the deployment to be created.
deployment-activation-time	string or null <date-time> Sets the date on which the process definitions contained in this deployment will be activated. This means that all process definitions will be deployed as usual, but they will be suspended from the start until the given activation date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
data	string or null <binary> The binary data to create the deployment resource. It is possible to have more than one form part with different form part names for the binary data to create a deployment.

Responses

Response samples

200
400

Content type

application/json

{"links": [{"method": "GET",
"href": "http://localhost:38080/rest-test/deployment/aDeploymentId",
"rel": "self"
}
],
"id": "aDeploymentId",
"name": "aName",
"source": "process application",
"deploymentTime": "2013-01-23T13:59:43.000+0200",
"tenantId": null,
"deployedProcessDefinitions": {"aProcDefId": {"id": "aProcDefId",
"key": "aKey",
"category": "aCategory",
"description": "aDescription",
"name": "aName",
"version": 42,
"resource": "aResourceName",
"deploymentId": "aDeploymentId",
"diagram": "aResourceName.png",
"suspended": true,
"tenantId": null,
"versionTag": null
}
},
"deployedCaseDefinitions": null,
"deployedDecisionDefinitions": null,
"deployedDecisionRequirementsDefinitions": null
}

Get Registered Deployments

Queries the registered deployment IDs for the current application.

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

The Response content of a status 200

["deploymentId1",
"deploymentId2",
"deploymentId3"
]

Delete

Deletes a deployment by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the deployment to be deleted.

query Parameters

cascade	boolean Default: false `true`, if all process instances, historic process instances and jobs for this deployment should be deleted.
skipCustomListeners	boolean Default: false `true`, if only the built-in ExecutionListeners should be notified with the end event.
skipIoMappings	boolean Default: false `true`, if all input/output mappings should not be invoked.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get

Retrieves a deployment by id, according to the Deployment interface of the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the deployment.

Responses

Response samples

200
404

Content type

application/json

{"id": "someDeploymentId",
"name": "deploymentName",
"source": "process application",
"deploymentTime": "2013-04-23T13:42:43.000+0200"
}

Redeploy

Re-deploys an existing deployment.

The deployment resources to re-deploy can be restricted by using the properties resourceIds or resourceNames. If no deployment resources to re-deploy are passed then all existing resources of the given deployment are re-deployed.

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the deployment to re-deploy.

Request Body schema: application/json

resourceIds	Array of strings or null A list of deployment resource ids to re-deploy.
resourceNames	Array of strings or null A list of deployment resource names to re-deploy.
source	string or null Sets the source of the deployment.

Responses

Request samples

Payload

Content type

application/json

{"resourceIds": ["aResourceId"
],
"resourceNames": ["aResourceName"
],
"source": "cockpit"
}

Response samples

200
404

Content type

application/json

{"links": [{"method": "GET",
"href": "http://localhost:38080/rest-test/deployment/aDeploymentId",
"rel": "self"
}
],
"id": "aDeploymentId",
"name": "aName",
"source": "cockpit",
"deploymentTime": "2015-10-13T13:59:43.000+0200",
"tenantId": null,
"deployedProcessDefinitions": {"aProcDefId": {"id": "aProcDefId",
"key": "aKey",
"category": "aCategory",
"description": "aDescription",
"name": "aName",
"version": 42,
"resource": "aResourceName",
"deploymentId": "aDeploymentId",
"diagram": "aResourceName.png",
"suspended": true,
"tenantId": null,
"versionTag": null
}
},
"deployedCaseDefinitions": null,
"deployedDecisionDefinitions": null,
"deployedDecisionRequirementsDefinitions": null
}

Get Resources

Retrieves all deployment resources of a given deployment.

Authorizations:

basicAuth

path Parameters

id

required

string

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

Responses

Response samples

200
404

Content type

application/json

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

Get Resource

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

Authorizations:

basicAuth

path Parameters

id required	string The id of the deployment
resourceId required	string The id of the deployment resource

Responses

Response samples

200
404

Content type

application/json

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

Get Resource (Binary)

Retrieves the binary content of a deployment resource for the given deployment by id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the deployment.
resourceId required	string The id of the deployment resource.

Responses

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Engine

Get List

Retrieves the names of all process engines available on your platform. Note: You cannot prepend /engine/{name} to this method.

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

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

Event Subscription

Get List

Queries for event subscriptions that fulfill given parameters. The size of the result set can be retrieved by using the Get Event Subscriptions count method.

Authorizations:

basicAuth

query Parameters

eventSubscriptionId	string Only select subscription with the given id.
eventName	string Only select subscriptions for events with the given name.
eventType	string Enum: "message" "signal" "compensate" "conditional" Only select subscriptions for events with the given type. Valid values: `message`, `signal`, `compensate` and `conditional`.
executionId	string Only select subscriptions that belong to an execution with the given id.
processInstanceId	string Only select subscriptions that belong to a process instance with the given id.
activityId	string Only select subscriptions that belong to an activity with the given id.
tenantIdIn	string Filter by a comma-separated list of tenant ids. Only select subscriptions that belong to one of the given tenant ids.
withoutTenantId	boolean Only select subscriptions which have no tenant id. Value may only be `true`, as `false` is the default behavior.
includeEventSubscriptionsWithoutTenantId	boolean Select event subscriptions which have no tenant id. Can be used in combination with tenantIdIn parameter. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "created" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

[{"id": "anId",
"eventType": "message",
"eventName": "anEventName",
"executionId": "anExecutionId",
"processInstanceId": "aProcessInstanceId",
"activityId": "anActivityId",
"createdDate": "2020-04-20T15:23:12.229+0200",
"tenantId": null
},
{"id": "anotherId",
"eventType": "message",
"eventName": "anotherEventName",
"executionId": "anotherExecutionId",
"processInstanceId": "anotherProcessInstanceId",
"activityId": "anotherActivityId",
"createdDate": "2020-04-20T15:20:12.229+0200",
"tenantId": null
}
]

Get List Count

Queries for the number of event subscriptions that fulfill given parameters. Takes the same parameters as the Get Event Subscriptions method.

Authorizations:

basicAuth

query Parameters

eventSubscriptionId	string Only select subscription with the given id.
eventName	string Only select subscriptions for events with the given name.
eventType	string Enum: "message" "signal" "compensate" "conditional" Only select subscriptions for events with the given type. Valid values: `message`, `signal`, `compensate` and `conditional`.
executionId	string Only select subscriptions that belong to an execution with the given id.
processInstanceId	string Only select subscriptions that belong to a process instance with the given id.
activityId	string Only select subscriptions that belong to an activity with the given id.
tenantIdIn	string Filter by a comma-separated list of tenant ids. Only select subscriptions that belong to one of the given tenant ids.
withoutTenantId	boolean Only select subscriptions which have no tenant id. Value may only be `true`, as `false` is the default behavior.
includeEventSubscriptionsWithoutTenantId	boolean Select event subscriptions which have no tenant id. Can be used in combination with tenantIdIn parameter. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

{"count": 1
}

Execution

Get Executions

Queries for the executions that fulfill given parameters. Parameters may be static as well as dynamic runtime properties of executions. The size of the result set can be retrieved by using the Get Execution Count method.

Authorizations:

basicAuth

query Parameters

businessKey	string Filter by the business key of the process instances the executions belong to.
processDefinitionId	string Filter by the process definition the executions run on.
processDefinitionKey	string Filter by the key of the process definition the executions run on.
processInstanceId	string Filter by the id of the process instance the execution belongs to.
activityId	string Filter by the id of the activity the execution currently executes.
signalEventSubscriptionName	string Select only those executions that expect a signal of the given name.
messageEventSubscriptionName	string Select only those executions that expect a message of the given name.
active	boolean Only include active executions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Only include suspended executions. Value may only be `true`, as `false` is the default behavior.
incidentId	string Filter by the incident id.
incidentType	string Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string Filter by the incident message. Exact match.
incidentMessageLike	string Filter by the incident message that the parameter is a substring of.
tenantIdIn	string Filter by a comma-separated list of tenant ids. An execution must have one of the given tenant ids.
variables	string Only include executions that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
processVariables	string Only include executions that belong to a process instance with variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Match all variable names provided in `variables` and `processVariables` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match all variable values provided in `variables` and `processVariables` case- insensitively. If set to `true` variableValue and variablevalue are treated as equal.
sortBy	string Enum: "instanceId" "definitionKey" "definitionId" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /execution?variables=myVariable_eq_camunda

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

Get Executions (POST)

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

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

businessKey	string or null Filter by the business key of the process instances the executions belong to.
processDefinitionId	string or null Filter by the process definition the executions run on.
processDefinitionKey	string or null Filter by the key of the process definition the executions run on.
processInstanceId	string or null Filter by the id of the process instance the execution belongs to.
activityId	string or null Filter by the id of the activity the execution currently executes.
signalEventSubscriptionName	string or null Select only those executions that expect a signal of the given name.
messageEventSubscriptionName	string or null Select only those executions that expect a message of the given name.
active	boolean or null Only include active executions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean or null Only include suspended executions. Value may only be `true`, as `false` is the default behavior.
incidentId	string or null Filter by the incident id.
incidentType	string or null Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string or null Filter by the incident message. Exact match.
incidentMessageLike	string or null Filter by the incident message that the parameter is a substring of.
tenantIdIn	Array of strings or null Filter by a list of tenant ids. An execution must have one of the given tenant ids.
	Array of objects or null (VariableQueryParameterDto) An array to only include executions that have variables with certain values. The array consists of objects with the three properties `name`, `operator` and `value`. `name (String)` is the variable name, `operator (String)` is the comparison operator to be used and `value` the variable value. `value` may be `String`, `Number` or `Boolean`. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`.
	Array of objects or null (VariableQueryParameterDto) An array to only include executions that belong to a process instance with variables with certain values. The array consists of objects with the three properties `name`, `operator` and `value`. `name (String)` is the variable name, `operator (String)` is the comparison operator to be used and `value` the variable value. `value` may be `String`, `Number` or `Boolean`. Valid operator values are: `eq` - equal to; `neq` - not equal to.
variableNamesIgnoreCase	boolean or null Match all variable names provided in `variables` and `processVariables` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match all variable values provided in `variables` and `processVariables` case- insensitively. If set to `true` variableValue and variablevalue are treated as equal.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Has no effect for the `/count` endpoint

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400

Content type

application/json

POST /execution

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

Get Execution Count

Queries for the number of executions that fulfill given parameters. Takes the same parameters as the Get Executions method.

Authorizations:

basicAuth

query Parameters

businessKey	string Filter by the business key of the process instances the executions belong to.
processDefinitionId	string Filter by the process definition the executions run on.
processDefinitionKey	string Filter by the key of the process definition the executions run on.
processInstanceId	string Filter by the id of the process instance the execution belongs to.
activityId	string Filter by the id of the activity the execution currently executes.
signalEventSubscriptionName	string Select only those executions that expect a signal of the given name.
messageEventSubscriptionName	string Select only those executions that expect a message of the given name.
active	boolean Only include active executions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Only include suspended executions. Value may only be `true`, as `false` is the default behavior.
incidentId	string Filter by the incident id.
incidentType	string Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string Filter by the incident message. Exact match.
incidentMessageLike	string Filter by the incident message that the parameter is a substring of.
tenantIdIn	string Filter by a comma-separated list of tenant ids. An execution must have one of the given tenant ids.
variables	string Only include executions that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
processVariables	string Only include executions that belong to a process instance with variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Match all variable names provided in `variables` and `processVariables` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match all variable values provided in `variables` and `processVariables` case- insensitively. If set to `true` variableValue and variablevalue are treated as equal.

Responses

Response samples

200
400

Content type

application/json

GET /execution/count?variables=myVariable_eq_camunda

{"count": 1
}

Get Execution Count (POST)

Queries for the number of executions that fulfill given parameters. This method takes the same message body as the Get Executions POST method and therefore it is slightly more powerful than the Get Execution Count method.

Authorizations:

basicAuth

Request Body schema: application/json

businessKey	string or null Filter by the business key of the process instances the executions belong to.
processDefinitionId	string or null Filter by the process definition the executions run on.
processDefinitionKey	string or null Filter by the key of the process definition the executions run on.
processInstanceId	string or null Filter by the id of the process instance the execution belongs to.
activityId	string or null Filter by the id of the activity the execution currently executes.
signalEventSubscriptionName	string or null Select only those executions that expect a signal of the given name.
messageEventSubscriptionName	string or null Select only those executions that expect a message of the given name.
active	boolean or null Only include active executions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean or null Only include suspended executions. Value may only be `true`, as `false` is the default behavior.
incidentId	string or null Filter by the incident id.
incidentType	string or null Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string or null Filter by the incident message. Exact match.
incidentMessageLike	string or null Filter by the incident message that the parameter is a substring of.
tenantIdIn	Array of strings or null Filter by a list of tenant ids. An execution must have one of the given tenant ids.
	Array of objects or null (VariableQueryParameterDto) An array to only include executions that have variables with certain values. The array consists of objects with the three properties `name`, `operator` and `value`. `name (String)` is the variable name, `operator (String)` is the comparison operator to be used and `value` the variable value. `value` may be `String`, `Number` or `Boolean`. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`.
	Array of objects or null (VariableQueryParameterDto) An array to only include executions that belong to a process instance with variables with certain values. The array consists of objects with the three properties `name`, `operator` and `value`. `name (String)` is the variable name, `operator (String)` is the comparison operator to be used and `value` the variable value. `value` may be `String`, `Number` or `Boolean`. Valid operator values are: `eq` - equal to; `neq` - not equal to.
variableNamesIgnoreCase	boolean or null Match all variable names provided in `variables` and `processVariables` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match all variable values provided in `variables` and `processVariables` case- insensitively. If set to `true` variableValue and variablevalue are treated as equal.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Has no effect for the `/count` endpoint

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400

Content type

application/json

POST /execution/count

{"count": 1
}

Get Execution

Retrieves an execution by id, according to the Execution interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the execution to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /execution/anExecutionId

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

Create Incident

Creates a custom incident with given properties.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the execution to create a new incident for.

Request Body schema: application/json

incidentType	string or null A type of the new incident.
configuration	string or null A configuration for the new incident.
message	string or null A message for the new incident.

Responses

Request samples

Payload

Content type

application/json

{"incidentType": "aType",
"configuration": "aConfiguration"
}

Response samples

200
400

Content type

application/json

POST /execution/anExecutionId/create-incident

{"id": "anIncidentId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anExecutionId",
"incidentTimestamp": "2014-03-01T08:00:00.000+0200",
"incidentType": "failedJob",
"activityId": "serviceTask",
"failedActivityId": "serviceTask",
"causeIncidentId": "aCauseIncidentId",
"rootCauseIncidentId": "aRootCauseIncidentId",
"configuration": "aConfiguration",
"tenantId": null,
"incidentMessage": "anIncidentMessage",
"jobDefinitionId": "aJobDefinitionId"
}

Get Local Execution Variables

Retrieves all variables of a given execution by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the execution to retrieve the variables from.

query Parameters

deserializeValues

boolean

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

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

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

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

Responses

Response samples

200
500

Content type

application/json

Example

GET `/execution/anExecutionId/localVariables`

GET /execution/anExecutionId/localVariables

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

Update/Delete Local Execution Variables

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the execution to set variables for.

Request Body schema: application/json

	object or null A JSON object containing variable key-value pairs.
deletions	Array of strings or null An array of String keys of variables to be deleted.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete Local Execution Variable

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

Authorizations:

basicAuth

path Parameters

id required	string The id of the execution to delete the variable from.
varName required	string The name of the variable to delete.

Responses

Get Local Execution Variable

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

Authorizations:

basicAuth

path Parameters

id required	string The id of the execution to retrieve the variable from.
varName required	string The name of the variable to get.

query Parameters

deserializeValue

boolean

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

If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to false, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.

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

Responses

Response samples

200
404

Content type

application/json

Example

GET `/execution/anExecutionId/localVariables/aVarName`

GET /execution/anExecutionId/localVariables/aVarName

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

Put Local Execution Variable

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

Authorizations:

basicAuth

path Parameters

id required	string The id of the execution to set the variable for.
varName required	string The name of the variable to set.

Request Body schema: application/json

value	any (AnyValue) Can be any value - string, number, boolean, array or object. Note: Not every endpoint supports every type.
type	string or null The value type of the variable.
	object A JSON object containing additional, value-type-dependent properties. For serialized variables of type Object, the following properties can be provided: `objectTypeName`: A string representation of the object's type name. `serializationDataFormat`: The serialization format used to store the variable. For serialized variables of type File, the following properties can be provided: `filename`: The name of the file. This is not the variable name but the name that will be used when downloading the file again. `mimetype`: The MIME type of the file that is being uploaded. `encoding`: The encoding of the file that is being uploaded. The following property can be provided for all value types: `transient`: Indicates whether the variable should be transient or not. See documentation for more informations. (Not applicable for `decision-definition`, `/process-instance/variables-async`, and `/migration/executeAsync` endpoints)

Responses

Request samples

Payload

Content type

application/json

Example

PUT `/execution/anExecutionId/localVariables/aVarName`

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

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Local Execution Variable (Binary)

Retrieves a binary variable from the context of a given execution by id. Does not traverse the parent execution hierarchy. Applicable for byte array and file variables.

Authorizations:

basicAuth

path Parameters

id required	string The id of the execution to retrieve the variable from.
varName required	string The name of the variable to get.

Responses

Response samples

200
400
404

Content type

application/octet-stream

Content-Type: application/octet-stream

Post Local Execution Variable (Binary)

Sets the serialized value for a binary variable or the binary value for a file variable in the context of a given execution by id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the execution to set the variable for.
varName required	string The name of the variable to set.

Request Body schema: multipart/form-data

data	string or null <binary> The binary data to be set. For File variables, this multipart can contain the filename, binary value and MIME type of the file variable to be set Only the filename is mandatory.
valueType	string or null Enum: "Bytes" "File" The name of the variable type. Either Bytes for a byte array variable or File for a file variable.

Responses

Request samples

Payload

Content type

multipart/form-data

Example

Post binary content of a byte array variable

POST /execution/anExecutionId/localVariables/aVarName/data


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

                        <<Byte Stream ommitted>>
                        ---OSQH1f8lzs83iXFHphqfIuitaQfNKFY74Y
                        Content-Disposition: form-data; name="valueType"
                        Content-Type: text/plain; charset=US-ASCII
                        Content-Transfer-Encoding: 8bit

                        Bytes
                        ---OSQH1f8lzs83iXFHphqfIuitaQfNKFY74Y--
                        ```

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Message Event Subscription

Retrieves a message event subscription for a given execution by id and a message name.

Authorizations:

basicAuth

path Parameters

id required	string The id of the execution that holds the subscription.
messageName required	string The name of the message that the subscription corresponds to.

Responses

Response samples

200
404

Content type

application/json

GET /execution/anExecutionId/messageSubscriptions/someMessage

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

Trigger Message Event Subscription

Delivers a message to a specific execution by id, to trigger an existing message event subscription. Inject process variables as the message's payload.

Authorizations:

basicAuth

path Parameters

id required	string The id of the execution to submit the message to.
messageName required	string The name of the message that the addressed subscription corresponds to.

Request Body schema: application/json

object or null

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Trigger Execution

Signals an execution by id. Can for example be used to explicitly skip user tasks or signal asynchronous continuations.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the execution to signal.

Request Body schema: application/json

object or null

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

Responses

Request samples

Payload

Content type

application/json

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

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

External Task

Get List

Queries for the external tasks 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 External Task Count method.

Authorizations:

basicAuth

query Parameters

externalTaskId	string Filter by an external task's id.
externalTaskIdIn	string Filter by the comma-separated list of external task ids.
topicName	string Filter by an external task topic.
workerId	string Filter by the id of the worker that the task was most recently locked by.
locked	boolean Only include external tasks that are currently locked (i.e., they have a lock time and it has not expired). Value may only be `true`, as `false` matches any external task.
notLocked	boolean Only include external tasks that are currently not locked (i.e., they have no lock or it has expired). Value may only be `true`, as `false` matches any external task.
withRetriesLeft	boolean Only include external tasks that have a positive (> 0) number of retries (or `null`). Value may only be `true`, as `false` matches any external task.
noRetriesLeft	boolean Only include external tasks that have 0 retries. Value may only be `true`, as `false` matches any external task.
lockExpirationAfter	string <date-time> Restrict to external tasks that have a lock that expires after a given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
lockExpirationBefore	string <date-time> Restrict to external tasks that have a lock that expires before a given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
activityId	string Filter by the id of the activity that an external task is created for.
activityIdIn	string Filter by the comma-separated list of ids of the activities that an external task is created for.
executionId	string Filter by the id of the execution that an external task belongs to.
processInstanceId	string Filter by the id of the process instance that an external task belongs to.
processInstanceIdIn	string Filter by a comma-separated list of process instance ids that an external task may belong to.
processDefinitionId	string Filter by the id of the process definition that an external task belongs to.
tenantIdIn	string Filter by a comma-separated list of tenant ids. An external task must have one of the given tenant ids.
active	boolean Only include active tasks. Value may only be `true`, as `false` matches any external task.
suspended	boolean Only include suspended tasks. Value may only be `true`, as `false` matches any external task.
priorityHigherThanOrEquals	integer <int64> Only include jobs with a priority higher than or equal to the given value. Value must be a valid `long` value.
priorityLowerThanOrEquals	integer <int64> Only include jobs with a priority lower than or equal to the given value. Value must be a valid `long` value.
sortBy	string Enum: "id" "lockExpirationTime" "processInstanceId" "processDefinitionId" "processDefinitionKey" "taskPriority" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

[{"activityId": "anActivityId",
"activityInstanceId": "anActivityInstanceId",
"errorMessage": "anErrorMessage",
"executionId": "anExecutionId",
"id": "anExternalTaskId",
"lockExpirationTime": "2015-10-06T16:34:42.000+0200",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"processInstanceId": "aProcessInstanceId",
"tenantId": null,
"retries": 3,
"suspended": false,
"workerId": "aWorkerId",
"topicName": "aTopic",
"priority": 9,
"businessKey": "aBusinessKey"
},
{"activityId": "anotherActivityId",
"activityInstanceId": "anotherActivityInstanceId",
"errorMessage": "anotherErrorMessage",
"executionId": "anotherExecutionId",
"id": "anotherExternalTaskId",
"lockExpirationTime": "2015-10-06T16:34:42.000+0200",
"processDefinitionId": "anotherProcessDefinitionId",
"processDefinitionKey": "anotherProcessDefinitionKey",
"processInstanceId": "anotherProcessInstanceId",
"tenantId": null,
"retries": 1,
"suspended": false,
"workerId": "aWorkerId",
"topicName": "aTopic",
"priority": 3,
"businessKey": "aBusinessKey"
}
]

Get List (POST)

Queries for external tasks that fulfill given parameters in the form of a JSON object.

This method is slightly more powerful than the Get External Tasks method because it allows to specify a hierarchical result sorting.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

externalTaskId	string or null Filter by an external task's id.
externalTaskIdIn	Array of strings or null Filter by the comma-separated list of external task ids.
topicName	string or null Filter by an external task topic.
workerId	string or null Filter by the id of the worker that the task was most recently locked by.
locked	boolean or null Only include external tasks that are currently locked (i.e., they have a lock time and it has not expired). Value may only be `true`, as `false` matches any external task.
notLocked	boolean or null Only include external tasks that are currently not locked (i.e., they have no lock or it has expired). Value may only be `true`, as `false` matches any external task.
withRetriesLeft	boolean or null Only include external tasks that have a positive (> 0) number of retries (or `null`). Value may only be `true`, as `false` matches any external task.
noRetriesLeft	boolean or null Only include external tasks that have 0 retries. Value may only be `true`, as `false` matches any external task.
lockExpirationAfter	string or null <date-time> Restrict to external tasks that have a lock that expires after a given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
lockExpirationBefore	string or null <date-time> Restrict to external tasks that have a lock that expires before a given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
activityId	string or null Filter by the id of the activity that an external task is created for.
activityIdIn	Array of strings or null Filter by the comma-separated list of ids of the activities that an external task is created for.
executionId	string or null Filter by the id of the execution that an external task belongs to.
processInstanceId	string or null Filter by the id of the process instance that an external task belongs to.
processInstanceIdIn	Array of strings or null Filter by a comma-separated list of process instance ids that an external task may belong to.
processDefinitionId	string or null Filter by the id of the process definition that an external task belongs to.
tenantIdIn	Array of strings or null Filter by a comma-separated list of tenant ids. An external task must have one of the given tenant ids.
active	boolean or null Only include active tasks. Value may only be `true`, as `false` matches any external task.
suspended	boolean or null Only include suspended tasks. Value may only be `true`, as `false` matches any external task.
priorityHigherThanOrEquals	integer or null <int64> Only include jobs with a priority higher than or equal to the given value. Value must be a valid `long` value.
priorityLowerThanOrEquals	integer or null <int64> Only include jobs with a priority lower than or equal to the given value. Value must be a valid `long` value.
	Array of objects or null A JSON array of criteria to sort the result by. Each element of the array is a JSON object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. The ordering objects have the following properties: Note: The `sorting` properties will not be applied to the External Task count query.

Responses

Request samples

Payload

Content type

application/json

{"processDefinitionId": "aProcessDefinitionId",
"sorting": [{"sortBy": "processDefinitionKey",
"sortOrder": "asc"
},
{"sortBy": "lockExpirationTime",
"sortOrder": "desc"
},
{"sortBy": "createTime",
"sortOrder": "asc"
}
]
}

Response samples

200
400

Content type

application/json

[{"activityId": "anActivityId",
"activityInstanceId": "anActivityInstanceId",
"errorMessage": "anErrorMessage",
"executionId": "anExecutionId",
"id": "anExternalTaskId",
"lockExpirationTime": "2015-10-06T16:34:42.000+0200",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"processInstanceId": "aProcessInstanceId",
"tenantId": null,
"retries": 3,
"suspended": false,
"workerId": "aWorkerId",
"topicName": "aTopic",
"priority": 9,
"businessKey": "aBusinessKey"
},
{"activityId": "anotherActivityId",
"activityInstanceId": "anotherActivityInstanceId",
"errorMessage": "anotherErrorMessage",
"executionId": "anotherExecutionId",
"id": "anotherExternalTaskId",
"lockExpirationTime": "2015-10-06T16:34:42.000+0200",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "anotherProcessDefinitionKey",
"processInstanceId": "anotherProcessInstanceId",
"tenantId": null,
"retries": 1,
"suspended": false,
"workerId": "aWorkerId",
"topicName": "aTopic",
"priority": 3,
"businessKey": "aBusinessKey"
}
]

Get List Count

Queries for the number of external tasks that fulfill given parameters. Takes the same parameters as the Get External Tasks method.

Authorizations:

basicAuth

query Parameters

externalTaskId	string Filter by an external task's id.
externalTaskIdIn	string Filter by the comma-separated list of external task ids.
topicName	string Filter by an external task topic.
workerId	string Filter by the id of the worker that the task was most recently locked by.
locked	boolean Only include external tasks that are currently locked (i.e., they have a lock time and it has not expired). Value may only be `true`, as `false` matches any external task.
notLocked	boolean Only include external tasks that are currently not locked (i.e., they have no lock or it has expired). Value may only be `true`, as `false` matches any external task.
withRetriesLeft	boolean Only include external tasks that have a positive (> 0) number of retries (or `null`). Value may only be `true`, as `false` matches any external task.
noRetriesLeft	boolean Only include external tasks that have 0 retries. Value may only be `true`, as `false` matches any external task.
lockExpirationAfter	string <date-time> Restrict to external tasks that have a lock that expires after a given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
lockExpirationBefore	string <date-time> Restrict to external tasks that have a lock that expires before a given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
activityId	string Filter by the id of the activity that an external task is created for.
activityIdIn	string Filter by the comma-separated list of ids of the activities that an external task is created for.
executionId	string Filter by the id of the execution that an external task belongs to.
processInstanceId	string Filter by the id of the process instance that an external task belongs to.
processInstanceIdIn	string Filter by a comma-separated list of process instance ids that an external task may belong to.
processDefinitionId	string Filter by the id of the process definition that an external task belongs to.
tenantIdIn	string Filter by a comma-separated list of tenant ids. An external task must have one of the given tenant ids.
active	boolean Only include active tasks. Value may only be `true`, as `false` matches any external task.
suspended	boolean Only include suspended tasks. Value may only be `true`, as `false` matches any external task.
priorityHigherThanOrEquals	integer <int64> Only include jobs with a priority higher than or equal to the given value. Value must be a valid `long` value.
priorityLowerThanOrEquals	integer <int64> Only include jobs with a priority lower than or equal to the given value. Value must be a valid `long` value.

Responses

Response samples

200
400

Content type

application/json

{"count": 42
}

Get List Count (POST)

Queries for the number of external tasks that fulfill given parameters. This method takes the same message body as the Get External Tasks (POST) method.

Authorizations:

basicAuth

Request Body schema: application/json

externalTaskId	string or null Filter by an external task's id.
externalTaskIdIn	Array of strings or null Filter by the comma-separated list of external task ids.
topicName	string or null Filter by an external task topic.
workerId	string or null Filter by the id of the worker that the task was most recently locked by.
locked	boolean or null Only include external tasks that are currently locked (i.e., they have a lock time and it has not expired). Value may only be `true`, as `false` matches any external task.
notLocked	boolean or null Only include external tasks that are currently not locked (i.e., they have no lock or it has expired). Value may only be `true`, as `false` matches any external task.
withRetriesLeft	boolean or null Only include external tasks that have a positive (> 0) number of retries (or `null`). Value may only be `true`, as `false` matches any external task.
noRetriesLeft	boolean or null Only include external tasks that have 0 retries. Value may only be `true`, as `false` matches any external task.
lockExpirationAfter	string or null <date-time> Restrict to external tasks that have a lock that expires after a given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
lockExpirationBefore	string or null <date-time> Restrict to external tasks that have a lock that expires before a given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
activityId	string or null Filter by the id of the activity that an external task is created for.
activityIdIn	Array of strings or null Filter by the comma-separated list of ids of the activities that an external task is created for.
executionId	string or null Filter by the id of the execution that an external task belongs to.
processInstanceId	string or null Filter by the id of the process instance that an external task belongs to.
processInstanceIdIn	Array of strings or null Filter by a comma-separated list of process instance ids that an external task may belong to.
processDefinitionId	string or null Filter by the id of the process definition that an external task belongs to.
tenantIdIn	Array of strings or null Filter by a comma-separated list of tenant ids. An external task must have one of the given tenant ids.
active	boolean or null Only include active tasks. Value may only be `true`, as `false` matches any external task.
suspended	boolean or null Only include suspended tasks. Value may only be `true`, as `false` matches any external task.
priorityHigherThanOrEquals	integer or null <int64> Only include jobs with a priority higher than or equal to the given value. Value must be a valid `long` value.
priorityLowerThanOrEquals	integer or null <int64> Only include jobs with a priority lower than or equal to the given value. Value must be a valid `long` value.
	Array of objects or null A JSON array of criteria to sort the result by. Each element of the array is a JSON object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. The ordering objects have the following properties: Note: The `sorting` properties will not be applied to the External Task count query.

Responses

Request samples

Payload

Content type

application/json

{"topicName": "aTopicName",
"withRetriesLeft": true
}

Response samples

200
400

Content type

application/json

{"count": 1
}

Fetch and Lock

Fetches and locks a specific number of external tasks for execution by a worker. Query can be restricted to specific task topics and for each task topic an individual lock time can be provided.

Authorizations:

basicAuth

Request Body schema: application/json

workerId required	string Mandatory. The id of the worker on which behalf tasks are fetched. The returned tasks are locked for that worker and can only be completed when providing the same worker id.
maxTasks required	integer or null <int32> Mandatory. The maximum number of tasks to return.
usePriority	boolean or null A `boolean` value, which indicates whether the task should be fetched based on its priority or arbitrarily.
asyncResponseTimeout	integer or null <int64> The Long Polling timeout in milliseconds. Note: The value cannot be set larger than 1.800.000 milliseconds (corresponds to 30 minutes).
	Array of objects or null (FetchExternalTaskTopicDto) A JSON array of topic objects for which external tasks should be fetched. The returned tasks may be arbitrarily distributed among these topics. Each topic object has the following properties:
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

Example

POST /external-task/fetchAndLock (1)

Request with variable filtering

{"workerId": "aWorkerId",
"maxTasks": 2,
"usePriority": true,
"topics": [{"topicName": "createOrder",
"lockDuration": 10000,
"variables": ["orderId"
]
}
]
}

Response samples

200
400

Content type

application/json

Example

POST /external-task/fetchAndLock (1)

Request with variable filtering

[{"activityId": "anActivityId",
"activityInstanceId": "anActivityInstanceId",
"errorMessage": "anErrorMessage",
"errorDetails": "anErrorDetails",
"executionId": "anExecutionId",
"id": "anExternalTaskId",
"lockExpirationTime": "2015-10-06T16:34:42.000+0200",
"createTime": "2015-10-06T16:34:42.000+0200",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"processInstanceId": "aProcessInstanceId",
"tenantId": null,
"retries": 3,
"workerId": "aWorkerId",
"priority": 4,
"topicName": "createOrder",
"variables": {"orderId": {"type": "String",
"value": "1234",
"valueInfo": { }
}
}
},
{"activityId": "anActivityId",
"activityInstanceId": "anActivityInstanceId",
"errorMessage": "anErrorMessage",
"errorDetails": "anotherErrorDetails",
"executionId": "anExecutionId",
"id": "anExternalTaskId",
"lockExpirationTime": "2015-10-06T16:34:42.000+0200",
"createTime": "2015-10-06T16:34:42.000+0200",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"processInstanceId": "aProcessInstanceId",
"tenantId": null,
"retries": 3,
"workerId": "aWorkerId",
"priority": 0,
"topicName": "createOrder",
"variables": {"orderId": {"type": "String",
"value": "3456",
"valueInfo": { }
}
}
}
]

Set Retries Sync

Sets the number of retries left to execute external tasks by id synchronously. If retries are set to 0, an incident is created.

Authorizations:

basicAuth

Request Body schema: application/json

retries	integer or null <int32> The number of retries to set for the external task. Must be >= 0. If this is 0, an incident is created and the task cannot be fetched anymore unless the retries are increased again. Can not be null.
externalTaskIds	Array of strings or null The ids of the external tasks to set the number of retries for.
processInstanceIds	Array of strings or null The ids of process instances containing the tasks to set the number of retries for.
	object (ExternalTaskQueryDto) A JSON object with the following properties:
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances

Responses

Request samples

Payload

Content type

application/json

{"retries": 123,
"externalTaskIds": ["anExternalTask",
"anotherExternalTask"
]
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Retries Async

Sets the number of retries left to execute external tasks by id asynchronously. If retries are set to 0, an incident is created.

Authorizations:

basicAuth

Request Body schema: application/json

retries	integer or null <int32> The number of retries to set for the external task. Must be >= 0. If this is 0, an incident is created and the task cannot be fetched anymore unless the retries are increased again. Can not be null.
externalTaskIds	Array of strings or null The ids of the external tasks to set the number of retries for.
processInstanceIds	Array of strings or null The ids of process instances containing the tasks to set the number of retries for.
	object (ExternalTaskQueryDto) A JSON object with the following properties:
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances

Responses

Request samples

Payload

Content type

application/json

{"retries": 123,
"externalTaskIds": ["anExternalTask",
"anotherExternalTask"
]
}

Response samples

200
400
404

Content type

application/json

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"jobsCreated": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"suspended": false,
"createUserId": "demo"
}

Get External Task Topic Names

Queries for distinct topic names of external tasks that fulfill given parameters. Query can be restricted to only tasks with retries left, tasks that are locked, or tasks that are unlocked. The parameters withLockedTasks and withUnlockedTasks are exclusive. Setting them both to true will return an empty list. Providing no parameters will return a list of all distinct topic names with external tasks.

Authorizations:

basicAuth

query Parameters

withLockedTasks	boolean Only include external tasks that are currently locked (i.e., they have a lock time and it has not expired). Value may only be `true`, as `false` matches any external task.
withUnlockedTasks	boolean Only include external tasks that are currently not locked (i.e., they have no lock or it has expired). Value may only be `true`, as `false` matches any external task.
withRetriesLeft	boolean Only include external tasks that have a positive (> 0) number of retries (or `null`). Value may only be `true`, as `false` matches any external task.

Responses

Response samples

200
400

Content type

application/json

["topic-a",
"topic-b",
"topic-c"
]

Get

Retrieves an external task by id, corresponding to the ExternalTask interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task to be retrieved.

Responses

Response samples

200
404

Content type

application/json

{"activityId": "anActivityId",
"activityInstanceId": "anActivityInstanceId",
"errorMessage": "anErrorMessage",
"executionId": "anExecutionId",
"id": "anExternalTaskId",
"lockExpirationTime": "2015-10-06T16:34:42.000+0200",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"processInstanceId": "aProcessInstanceId",
"tenantId": null,
"retries": 3,
"suspended": false,
"workerId": "aWorkerId",
"priority": 0,
"topicName": "aTopic",
"businessKey": "aBusinessKey"
}

Handle BPMN Error

Reports a business error in the context of a running external task by id. The error code must be specified to identify the BPMN error handler.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task in which context a BPMN error is reported.

Request Body schema: application/json

workerId	string or null The id of the worker that reports the failure. Must match the id of the worker who has most recently locked the task.
errorCode	string or null An error code that indicates the predefined error. It is used to identify the BPMN error handler.
errorMessage	string or null An error message that describes the error.
	object or null A JSON object containing variable key-value pairs.

Responses

Request samples

Payload

Content type

application/json

{"workerId": "aWorker",
"errorCode": "bpmn-error",
"errorMessage": "anErrorMessage",
"variables": {"aVariable": {"value": "aStringValue",
"type": "String"
},
"anotherVariable": {"value": true,
"type": "Boolean"
}
}
}

Response samples

400
404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Complete

Completes an external task by id and updates process variables.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to complete.

Request Body schema: application/json

	object or null A JSON object containing variable key-value pairs. Each key is a variable name and each value a JSON variable value object with the following properties:
	object or null A JSON object containing local variable key-value pairs. Local variables are set only in the scope of external task. Each key is a variable name and each value a JSON variable value object with the following properties:
workerId	string Mandatory. The ID of the worker who is performing the operation on the external task. If the task is already locked, must match the id of the worker who has most recently locked the task.

Responses

Request samples

Payload

Content type

application/json

{"workerId": "aWorker",
"variables": {"aVariable": {"value": "aStringValue"
},
"anotherVariable": {"value": 42
},
"aThirdVariable": {"value": true
}
},
"localVariables": {"aLocalVariable": {"value": "aStringValue"
}
}
}

Response samples

400
404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Error Details

Retrieves the error details in the context of a running external task by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task for which the error details should be retrieved.

Responses

Response samples

200
500

Content type

text/plain

org.apache.ibatis.jdbc.RuntimeSqlException: org.apache.ibatis.jdbc.RuntimeSqlException: test cause
                  at org.camunda.bpm.engine.test.api.externaltask.ExternalTaskServiceTest.testHandleFailureWithErrorDetails(ExternalTaskServiceTest.java:1424)
                  at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
                  at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
                  at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)

Extend Lock

Extends the timeout of the lock by a given amount of time.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task.

Request Body schema: application/json

newDuration	integer or null <int64> An amount of time (in milliseconds). This is the new lock duration starting from the current moment.
workerId	string Mandatory. The ID of the worker who is performing the operation on the external task. If the task is already locked, must match the id of the worker who has most recently locked the task.

Responses

Request samples

Payload

Content type

application/json

{"workerId": "anId",
"newDuration": 100000
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Handle Failure

Reports a failure to execute an external task by id. A number of retries and a timeout until the task can be retried can be specified. If retries are set to 0, an incident for this task is created.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task to report a failure for.

Request Body schema: application/json

errorMessage	string or null An message indicating the reason of the failure.
errorDetails	string or null A detailed error description.
retries	integer or null <int32> A number of how often the task should be retried. Must be >= 0. If this is 0, an incident is created and the task cannot be fetched anymore unless the retries are increased again. The incident's message is set to the `errorMessage` parameter.
retryTimeout	integer or null <int64> A timeout in milliseconds before the external task becomes available again for fetching. Must be >= 0.
	object or null A JSON object containing variable key-value pairs. Each key is a variable name and each value a JSON variable value object with the following properties:
	object or null A JSON object containing local variable key-value pairs. Local variables are set only in the scope of external task. Each key is a variable name and each value a JSON variable value object with the following properties:
workerId	string Mandatory. The ID of the worker who is performing the operation on the external task. If the task is already locked, must match the id of the worker who has most recently locked the task.

Responses

Request samples

Payload

Content type

application/json

{"workerId": "aWorker",
"errorMessage": "Does not compute",
"retries": 3,
"retryTimeout": 60000
}

Response samples

400
404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

lock

Lock an external task by a given id for a specified worker and amount of time.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task.

Request Body schema: application/json

lockDuration	integer <int64> The duration to lock the external task for in milliseconds. Note: Attempting to lock an already locked external task with the same `workerId` will succeed and a new lock duration will be set, starting from the current moment.
workerId	string Mandatory. The ID of the worker who is performing the operation on the external task. If the task is already locked, must match the id of the worker who has most recently locked the task.

Responses

Request samples

Payload

Content type

application/json

{"workerId": "anId",
"lockDuration": 100000
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Priority

Sets the priority of an existing external task by id. The default value of a priority is 0.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task to set the priority for.

Request Body schema: application/json

priority

integer or null <int64>

The priority of the resource.

Responses

Request samples

Payload

Content type

application/json

{"priority": 5
}

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Retries

Sets the number of retries left to execute an external task by id. If retries are set to 0, an incident is created.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task to set the number of retries for.

Request Body schema: application/json

retries

integer or null <int32>

The number of retries to set for the resource. Must be >= 0. If this is 0, an incident is created and the task, or job, cannot be fetched, or acquired anymore unless the retries are increased again. Can not be null.

Responses

Request samples

Payload

Content type

application/json

{"retries": 123
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Unlock

Unlocks an external task by id. Clears the task's lock expiration time and worker id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the external task to unlock.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Filter

Get Filters

Queries for a list of filters using a list of parameters. The size of the result set can be retrieved by using the Get Filter Count method.

Authorizations:

basicAuth

query Parameters

filterId	string Filter by the id of the filter.
resourceType	string Filter by the resource type of the filter, e.g., `Task`.
name	string Filter by the name of the filter.
nameLike	string Filter by the name that the parameter is a substring of.
owner	string Filter by the user id of the owner of the filter.
itemCount	boolean If set to `true`, each filter result will contain an `itemCount` property with the number of items matched by the filter itself.
sortBy	string Enum: "filterId" "resourceType" "name" "owner" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

Example

request

GET /filter?resourceType=Task

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

Filter Resource Options

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

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

OPTIONS /filter

{"links": [{"method": "GET",
"href": "http://localhost:8080/engine-rest/filter",
"rel": "list"
},
{"method": "GET",
"href": "http://localhost:8080/engine-rest/filter/count",
"rel": "count"
},
{"method": "POST",
"href": "http://localhost:8080/engine-rest/filter/create",
"rel": "create"
}
]
}

Get Filter Count

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

Authorizations:

basicAuth

query Parameters

filterId	string Filter by the id of the filter.
resourceType	string Filter by the resource type of the filter, e.g., `Task`.
name	string Filter by the name of the filter.
nameLike	string Filter by the name that the parameter is a substring of.
owner	string Filter by the user id of the owner of the filter.

Responses

Response samples

200
400

Content type

application/json

GET /filter/count?resourceType=Task&owner=aUserId

{"count": 3
}

Create Filter

Creates a new filter.

Authorizations:

basicAuth

Request Body schema: application/json

resourceType	string or null The resource type of the filter.
name	string or null The name of the filter.
owner	string or null The user id of the owner of the filter.
query	object The query of the filter as a JSON object.
properties	object The properties of a filter as a JSON object.

Responses

Request samples

Payload

Content type

application/json

POST /filter/create

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

Response samples

200
400
403

Content type

application/json

POST /filter/create

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

Delete Filter

Deletes a filter by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to be deleted.

Responses

Response samples

403
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Single Filter

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to be retrieved.

query Parameters

itemCount

boolean

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

Responses

Response samples

200
403
404

Content type

application/json

Example

request

GET /filter/aFilterId

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

Filter Resource Options

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to be checked.

Responses

Response samples

200

Content type

application/json

OPTIONS /filter/aFilterId

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

Update Filter

Updates an existing filter.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to be updated.

Request Body schema: application/json

resourceType	string or null The resource type of the filter.
name	string or null The name of the filter.
owner	string or null The user id of the owner of the filter.
query	object The query of the filter as a JSON object.
properties	object The properties of a filter as a JSON object.

Responses

Request samples

Payload

Content type

application/json

PUT /filter/aFilterID

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

Response samples

400
403
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Execute Filter Count

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to execute.

Responses

Response samples

200
403
404

Content type

application/json

GET /filter/aTaskFilterId/count

{"count": 2
}

Execute Filter Count (POST)

Executes the saved query of the filter by id and returns the count. This method is slightly more powerful then the Get Execute Filter Count method because it allows to extend the saved query of the filter.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to execute.

Request Body schema: application/json

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

object

Responses

Request samples

Payload

Content type

application/json

POST filter/aTaskFilterId/singleResult. Note: The examples show a task filter. So the request body corresponds to a task query. For other resource types the request body will differ.

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

Response samples

200
400
403
404

Content type

application/json

POST filter/aTaskFilterId/singleResult

{"count": 1
}

Execute Filter List

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to execute.

query Parameters

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

Responses

Response samples

200
403
404

Content type

application/json

GET /filter/aTaskFilterId/list/?firstResult=0&maxResults=2. Note: The examples show the result of a task filter. So the response corresponds to a task, but for other filters the response format will differ.

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

Execute Filter List (POST)

Executes the saved query of the filter by id and returns the result list. This method is slightly more powerful then the Get Execute FilterList method because it allows to extend the saved query of the filter.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to execute.

query Parameters

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

Request Body schema: application/json

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

object

Responses

Request samples

Payload

Content type

application/json

POST /filter/aTaskFilterId/list/?firstResult=0&maxResults=2. Note: The examples show a task filter. So the request body corresponds to a task query. For other resource types the request body will differ.

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

Response samples

200
400
403
404

Content type

application/json

POST /filter/aTaskFilterId/list/?firstResult=0&maxResults=2. Note: The examples show the result of a task filter. So the response corresponds to a task, but for other filters the response format will differ.

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

Execute Filter Single Result

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to execute.

Responses

Response samples

200
400
403
404

Content type

application/json

GET /filter/aTaskFilterId/singleResult. Note: The examples show the result of a task filter. So the response corresponds to a task, but for other filters the response format will differ.

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

Execute Filter Single Result (POST)

Executes the saved query of the filter by id and returns the single result. This method is slightly more powerful then the Get Execute Filter Single Result method because it allows to extend the saved query of the filter.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the filter to execute.

Request Body schema: application/json

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

object

Responses

Request samples

Payload

Content type

application/json

POST filter/aTaskFilterId/singleResult. Note: The examples show a task filter. So the request body corresponds to a task query. For other resource types the request body will differ.

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

Response samples

200
400
403
404

Content type

application/json

POST filter/aTaskFilterId/singleResult. Note: The examples show the result of a task filter. So the response corresponds to a task, but for other filters the response format will differ.

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

Group

Get List

Queries for a list of groups using a list of parameters. The size of the result set can be retrieved by using the Get Group Count method.

Authorizations:

basicAuth

query Parameters

sortBy	string Enum: "id" "name" "type" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
id	string Filter by the id of the group.
idIn	string Filter by a comma seperated list of group ids.
name	string Filter by the name of the group.
nameLike	string Filter by the name that the parameter is a substring of.
type	string Filter by the type of the group.
member	string Only retrieve groups where the given user id is a member of.
memberOfTenant	string Only retrieve groups which are members of the given tenant.

Responses

Response samples

200
400

Content type

application/json

GET /group?name=Sales

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

Group Resource Options

The /group resource supports two custom OPTIONS requests, this 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. If the user can perform an operation or not may depend on various things, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

OPTIONS /group

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

Get List (POST)

Queries for a list of groups using a list of parameters. The size of the result set can be retrieved by using the Get Group Count (POST) method.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

id	string or null Filter by the id of the group.
idIn	Array of strings or null Filter by a JSON string array of group ids.
name	string or null Filter by the name of the group.
nameLike	string or null Filter by the name that the parameter is a substring of.
type	string or null Filter by the type of the group.
member	string or null Only retrieve groups where the given user id is a member of.
memberOfTenant	string or null Only retrieve groups which are members of the given tenant.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

{"name": "Sales"
}

Response samples

200
400

Content type

application/json

POST /group

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

Get List Count

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

Authorizations:

basicAuth

query Parameters

id	string Filter by the id of the group.
idIn	string Filter by a comma seperated list of group ids.
name	string Filter by the name of the group.
nameLike	string Filter by the name that the parameter is a substring of.
type	string Filter by the type of the group.
member	string Only retrieve groups where the given user id is a member of.
memberOfTenant	string Only retrieve groups which are members of the given tenant.

Responses

Response samples

200
400

Content type

application/json

GET /group/count?name=Sales

{"count": 1
}

Get List Count (POST)

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

Authorizations:

basicAuth

Request Body schema: application/json

id	string or null Filter by the id of the group.
idIn	Array of strings or null Filter by a JSON string array of group ids.
name	string or null Filter by the name of the group.
nameLike	string or null Filter by the name that the parameter is a substring of.
type	string or null Filter by the type of the group.
member	string or null Only retrieve groups where the given user id is a member of.
memberOfTenant	string or null Only retrieve groups which are members of the given tenant.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

{"name": "Sales"
}

Response samples

200
400

Content type

application/json

POST /group/count

{"count": 1
}

Create Group

Creates a new group.

Authorizations:

basicAuth

Request Body schema: application/json

id	string or null The id of the group.
name	string or null The name of the group.
type	string or null The type of the group.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete Group

Deletes a group by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the group to be deleted.

Responses

Response samples

403
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Group

Retrieves a group by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the group to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /group/sales

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

Group Resource Instance Options

The /group resource supports two custom OPTIONS requests, one for the resource as such and this 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/{id} resource instance. If the user can perform an operation or not may depend on various things, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the group.

Responses

Response samples

200

Content type

application/json

OPTIONS /group/aGroupId

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

Update Group

Updates a given group by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the group.

Request Body schema: application/json

id	string or null The id of the group.
name	string or null The name of the group.
type	string or null The type of the group.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

403
404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Group Membership Resource Options

The OPTIONS request allows checking for the set of available operations that the currently authenticated user can perform on the resource. If the user can perform an operation or not may depend on various things, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the group.

Responses

Response samples

200

Content type

application/json

OPTIONS /group/sales/members

{"links": [{"method": "DELETE",
"href": "http://localhost:8080/engine-rest/group/sales/members",
"rel": "delete"
},
{"method": "PUT",
"href": "http://localhost:8080/engine-rest/group/sales/members",
"rel": "create"
}
]
}

Delete a Group Member

Removes a member from a group.

Authorizations:

basicAuth

path Parameters

id required	string The id of the group.
userId required	string The id of user to remove from the group.

Responses

Response samples

403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Create Group Member

Adds a member to a group.

Authorizations:

basicAuth

path Parameters

id required	string The id of the group.
userId required	string The id of user to add to the group.

Responses

Response samples

403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Historic Activity Instance

Get List

Queries for historic activity instances that fulfill the given parameters. The size of the result set can be retrieved by using the Get Historic Activity Instance Count method.

Authorizations:

basicAuth

query Parameters

sortBy	string Enum: "activityInstanceId" "instanceId" "executionId" "activityId" "activityName" "activityType" "startTime" "endTime" "duration" "definitionId" "occurrence" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
activityInstanceId	string Filter by activity instance id.
processInstanceId	string Filter by process instance id.
processDefinitionId	string Filter by process definition id.
executionId	string Filter by the id of the execution that executed the activity instance.
activityId	string Filter by the activity id (according to BPMN 2.0 XML).
activityName	string Filter by the activity name (according to BPMN 2.0 XML).
activityType	string Filter by activity type.
taskAssignee	string Only include activity instances that are user tasks and assigned to a given user.
finished	boolean Only include finished activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
unfinished	boolean Only include unfinished activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
canceled	boolean Only include canceled activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
completeScope	boolean Only include activity instances which completed a scope. Value may only be `true`, as `false` behaves the same as when the property is not set.
startedBefore	string <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string <date-time> Restrict to instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string <date-time> Restrict to instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
tenantIdIn	string Filter by a comma-separated list of ids. An activity instance must have one of the given tenant ids.
withoutTenantId	boolean Only include historic activity instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

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

[{"activityId": "anActivity",
"activityName": "anActivityName",
"activityType": "userTask",
"assignee": "peter",
"calledProcessInstanceId": "aHistoricCalledProcessInstanceId",
"calledCaseInstanceId": null,
"canceled": true,
"completeScope": false,
"durationInMillis": 2000,
"endTime": "2013-04-23T18:42:43.000+0200",
"executionId": "anExecutionId",
"id": "aHistoricActivityInstanceId",
"parentActivityInstanceId": "aHistoricParentActivityInstanceId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"startTime": "2013-04-23T11:20:43.000+0200",
"taskId": "aTaskId",
"tenantId": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Get List (POST)

Queries for historic activity instances that fulfill the given parameters. The size of the result set can be retrieved by using the Get Historic Activity Instance Count method.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

activityInstanceId	string or null Filter by activity instance id.
processInstanceId	string or null Filter by process instance id.
processDefinitionId	string or null Filter by process definition id.
executionId	string or null Filter by the id of the execution that executed the activity instance.
activityId	string or null Filter by the activity id (according to BPMN 2.0 XML).
activityName	string or null Filter by the activity name (according to BPMN 2.0 XML).
activityType	string or null Filter by activity type.
taskAssignee	string or null Only include activity instances that are user tasks and assigned to a given user.
finished	boolean or null Only include finished activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
unfinished	boolean or null Only include unfinished activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
canceled	boolean or null Only include canceled activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
completeScope	boolean or null Only include activity instances which completed a scope. Value may only be `true`, as `false` behaves the same as when the property is not set.
startedBefore	string or null <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string or null <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string or null <date-time> Restrict to instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string or null <date-time> Restrict to instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
tenantIdIn	Array of strings or null Must be a JSON array of Strings. An activity instance must have one of the given tenant ids.
withoutTenantId	boolean or null Only include historic activity instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

{"activityType": "userTask",
"taskAssignee": "peter",
"sorting": [{"sortBy": "activityId",
"sortOrder": "asc"
},
{"sortBy": "executionId",
"sortOrder": "desc"
}
]
}

Response samples

200
400

Content type

application/json

[{"activityId": "anActivity",
"activityName": "anActivityName",
"activityType": "userTask",
"assignee": "peter",
"calledProcessInstanceId": "aHistoricCalledProcessInstanceId",
"calledCaseInstanceId": null,
"canceled": true,
"completeScope": false,
"durationInMillis": 2000,
"endTime": "2013-04-23T18:42:43.000+0200",
"executionId": "anExecutionId",
"id": "aHistoricActivityInstanceId",
"parentActivityInstanceId": "aHistoricParentActivityInstanceId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"startTime": "2013-04-23T11:20:43.000+0200",
"taskId": "aTaskId",
"tenantId": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Get List Count

Queries for the number of historic activity instances that fulfill the given parameters. Takes the same parameters as the Get Historic Activity Instance method.

Authorizations:

basicAuth

query Parameters

activityInstanceId	string Filter by activity instance id.
processInstanceId	string Filter by process instance id.
processDefinitionId	string Filter by process definition id.
executionId	string Filter by the id of the execution that executed the activity instance.
activityId	string Filter by the activity id (according to BPMN 2.0 XML).
activityName	string Filter by the activity name (according to BPMN 2.0 XML).
activityType	string Filter by activity type.
taskAssignee	string Only include activity instances that are user tasks and assigned to a given user.
finished	boolean Only include finished activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
unfinished	boolean Only include unfinished activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
canceled	boolean Only include canceled activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
completeScope	boolean Only include activity instances which completed a scope. Value may only be `true`, as `false` behaves the same as when the property is not set.
startedBefore	string <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string <date-time> Restrict to instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string <date-time> Restrict to instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
tenantIdIn	string Filter by a comma-separated list of ids. An activity instance must have one of the given tenant ids.
withoutTenantId	boolean Only include historic activity instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

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

{"count": 1
}

Get List Count (POST)

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

Authorizations:

basicAuth

Request Body schema: application/json

activityInstanceId	string or null Filter by activity instance id.
processInstanceId	string or null Filter by process instance id.
processDefinitionId	string or null Filter by process definition id.
executionId	string or null Filter by the id of the execution that executed the activity instance.
activityId	string or null Filter by the activity id (according to BPMN 2.0 XML).
activityName	string or null Filter by the activity name (according to BPMN 2.0 XML).
activityType	string or null Filter by activity type.
taskAssignee	string or null Only include activity instances that are user tasks and assigned to a given user.
finished	boolean or null Only include finished activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
unfinished	boolean or null Only include unfinished activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
canceled	boolean or null Only include canceled activity instances. Value may only be `true`, as `false` behaves the same as when the property is not set.
completeScope	boolean or null Only include activity instances which completed a scope. Value may only be `true`, as `false` behaves the same as when the property is not set.
startedBefore	string or null <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string or null <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string or null <date-time> Restrict to instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string or null <date-time> Restrict to instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
tenantIdIn	Array of strings or null Must be a JSON array of Strings. An activity instance must have one of the given tenant ids.
withoutTenantId	boolean or null Only include historic activity instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

{"activityType": "userTask"
}

Response samples

200
400

Content type

application/json

{"count": 1
}

Get

Retrieves a historic activity instance by id, according to the HistoricActivityInstance interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the historic activity instance to be retrieved.

Responses

Response samples

200
404

Content type

application/json

{"id": "aActivityInstId",
"activityId": "anActivity",
"activityName": "anActivityName",
"activityType": "userTask",
"assignee": "peter",
"calledProcessInstanceId": "aHistoricCalledProcessInstanceId",
"calledCaseInstanceId": null,
"canceled": true,
"completeScope": false,
"durationInMillis": 2000,
"endTime": "2013-04-23T18:42:43.000+0200",
"executionId": "anExecutionId",
"parentActivityInstanceId": "aHistoricParentActivityInstanceId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"startTime": "2013-04-23T11:20:43.000+0200",
"taskId": "aTaskId",
"tenantId": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}

Historic Batch

Get Historic Batches

Queries for historic batches that fulfill given parameters. Parameters may be the properties of batches, such as the id or type. The size of the result set can be retrieved by using the Get Historic Batch Count method.

Authorizations:

basicAuth

query Parameters

batchId	string Filter by batch id.
type	string Filter by batch type. See the User Guide for more information about batch types.
completed	boolean Filter completed or not completed batches. If the value is `true`, only completed batches, i.e., end time is set, are returned. Otherwise, if the value is `false`, only running batches, i.e., end time is null, are returned.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A batch matches if it has one of the given tenant ids.
withoutTenantId	boolean Only include batches which belong to no tenant. Value can effectively only be `true`, as `false` is the default behavior.
sortBy	string Enum: "batchId" "startTime" "endTime" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /history/batch?type=aBatchType&completed=true&sortBy=batchId&sortOrder=asc

[{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"createUserId": "aUserId",
"startTime": "2016-04-12T15:29:33.000+0200",
"endTime": "2016-04-12T16:23:34.000+0200",
"removalTime": "2016-04-15T16:23:34.000+0200"
}
]

Get Cleanable Batch Report

Retrieves a report about a historic batch operations relevant to history cleanup (see History cleanup ) so that you can tune the history time to live. These reports include the count of the finished batches, cleanable batches and type of the batch. The size of the result set can be retrieved by using the Get Cleanable Batch Report Count method.

Please note: The history time to live for batch operations does not support Multi-Tenancy. The report will return an information for all batch operations (for all tenants) if you have permissions to see the history.

Authorizations:

basicAuth

query Parameters

sortBy	string Value: "finished" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
500

Content type

application/json

GET /history/batch/cleanable-batch-report

                                  An array containing finished batches information relevant to history cleanup.

[{"batchType": "instance-modification",
"historyTimeToLive": 5,
"finishedBatchCount": 100,
"cleanableBatchCount": 53
},
{"batchType": "instance-deletion",
"historyTimeToLive": 5,
"finishedBatchCount": 1000,
"cleanableBatchCount": 13
}
]

Get Cleanable Batch Report Count

Queries for the number of report results about a historic batch operations relevant to history cleanup (see History cleanup ). Takes the same parameters as the Get Cleanable Batch Report method.

Authorizations:

basicAuth

Responses

Response samples

200
500

Content type

application/json

GET /history/batch/cleanable-batch-report/count

{"count": 10
}

Get Historic Batch Count

Requests the number of historic batches that fulfill the query criteria. Takes the same filtering parameters as the Get Historic Batches method.

Authorizations:

basicAuth

query Parameters

batchId	string Filter by batch id.
type	string Filter by batch type. See the User Guide for more information about batch types.
completed	boolean Filter completed or not completed batches. If the value is `true`, only completed batches, i.e., end time is set, are returned. Otherwise, if the value is `false`, only running batches, i.e., end time is null, are returned.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A batch matches if it has one of the given tenant ids.
withoutTenantId	boolean Only include batches which belong to no tenant. Value can effectively only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

GET /history/batch/count?type=aBatchType

{"count": 1
}

Set Removal Time Async (POST)

Sets the removal time to multiple historic batches asynchronously (batch).

At least historicBatchIds or historicBatchQuery has to be provided. If both are provided, all instances matching query criterion and instances from the list will be updated with a removal time.

Authorizations:

basicAuth

Request Body schema: application/json

historicBatchQuery	object or null Query for the historic batches to set the removal time for.
historicBatchIds	Array of strings or null The ids of the historic batches to set the removal time for.
absoluteRemovalTime	string or null <date-time> The date for which the instances shall be removed. Value may not be `null`. Note: Cannot be set in conjunction with `clearedRemovalTime` or `calculatedRemovalTime`.
clearedRemovalTime	boolean or null Sets the removal time to `null`. Value may only be `true`, as `false` is the default behavior. Note: Cannot be set in conjunction with `absoluteRemovalTime` or `calculatedRemovalTime`.
calculatedRemovalTime	boolean or null The removal time is calculated based on the engine's configuration settings. Value may only be `true`, as `false` is the default behavior. Note: Cannot be set in conjunction with `absoluteRemovalTime` or `clearedRemovalTime`.

Responses

Request samples

Payload

Content type

application/json

{"absoluteRemovalTime": "2019-05-05T11:56:24.725+0200",
"historicBatchQuery": {"completed": true
},
"historicBatchIds": ["b4d2ad98-7240-11e9-98b7-be5e0f7575b7",
"b4d2ad94-7240-11e9-98b7-be5e0f7575b7"
]
}

Response samples

200
400

Content type

application/json

POST /history/batch/set-removal-time

{"id": "120b568d-724a-11e9-98b7-be5e0f7575b7",
"type": "batch-set-removal-time",
"totalJobs": 12,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "120b5690-724a-11e9-98b7-be5e0f7575b7",
"monitorJobDefinitionId": "120b568f-724a-11e9-98b7-be5e0f7575b7",
"batchJobDefinitionId": "120b568e-724a-11e9-98b7-be5e0f7575b7",
"tenantId": "accounting"
}

Delete Historic Batch

Deletes a historic batch by id, including related historic job logs.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the batch to be deleted.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Historic Batch

Retrieves a historic batch by id, according to the HistoricBatch interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the historic batch to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /history/batch/aBatchId

{"id": "aBatchId",
"type": "aBatchType",
"size": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"createUserId": "aUserId",
"startTime": "2016-04-12T15:29:33.000+0200",
"endTime": "2016-04-12T16:23:34.000+0200",
"removalTime": "2016-04-15T16:23:34.000+0200"
}

Historic Decision Definition

Get Cleanable Decision Instance Report

Retrieves a report about a decision definition and finished decision instances relevant to history cleanup (see History cleanup), so that you can tune the history time to live. These reports include the count of the finished historic decision instances, cleanable decision instances and basic decision definition data - id, key, name and version. The size of the result set can be retrieved by using the Get Cleanable Decision Instance Report Count method.

Authorizations:

basicAuth

query Parameters

decisionDefinitionIdIn	string Filter by decision definition ids. Must be a comma-separated list of decision definition ids.
decisionDefinitionKeyIn	string Filter by decision definition keys. Must be a comma-separated list of decision definition keys.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A decision definition must have one of the given tenant ids.
withoutTenantId	boolean Only include decision definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
compact	boolean Only include decision instances which have more than zero finished instances. Value may only be `true`, as `false` is the default behavior.
sortBy	string Value: "finished" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/history/decision-definition/cleanable-decision-instance-report

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/history/decision-definition/cleanable-decision-instance-report

The API server with a custom url

/{url}/history/decision-definition/cleanable-decision-instance-report

Response samples

200
500

Content type

application/json

GET /history/decision-definition/cleanable-decision-instance-report

[{"decisionDefinitionId": "invoice:1:7bf79f13-ef95-11e6-b6e6-34f39ab71d4e",
"decisionDefinitionKey": "invoice",
"decisionDefinitionName": "Invoice Receipt",
"decisionDefinitionVersion": 1,
"historyTimeToLive": 5,
"finishedDecisionInstanceCount": 100,
"cleanableDecisionInstanceCount": 53,
"tenantId": "aTenantId"
},
{"decisionDefinitionId": "invoice:2:7bf79f13-ef95-11e6-b6e6-34f39ab71d4e",
"decisionDefinitionKey": "invoice",
"decisionDefinitionName": "Invoice Receipt v2.0",
"decisionDefinitionVersion": 2,
"historyTimeToLive": 5,
"finishedDecisionInstanceCount": 1000,
"cleanableDecisionInstanceCount": 13,
"tenantId": "aTenantId"
}
]

Get Cleanable Decision Instance Report Count

Queries for the number of report results about a decision definition and finished decision instances relevant to history cleanup (see History cleanup). Takes the same parameters as the Get Cleanable Decision Instance Report method.

Authorizations:

basicAuth

query Parameters

decisionDefinitionIdIn	string Filter by decision definition ids. Must be a comma-separated list of decision definition ids.
decisionDefinitionKeyIn	string Filter by decision definition keys. Must be a comma-separated list of decision definition keys.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A decision definition must have one of the given tenant ids.
withoutTenantId	boolean Only include decision definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
compact	boolean Only include decision instances which have more than zero finished instances. Value may only be `true`, as `false` is the default behavior.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/history/decision-definition/cleanable-decision-instance-report/count

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/history/decision-definition/cleanable-decision-instance-report/count

The API server with a custom url

/{url}/history/decision-definition/cleanable-decision-instance-report/count

Response samples

200
500

Content type

application/json

GET /history/decision-definition/cleanable-decision-instance-report/count

{"count": 1
}

Historic Decision Instance

Get Historic Decision Instances

Queries for historic decision instances that fulfill the given parameters. The size of the result set can be retrieved by using the Get Historic Decision Instance Count method.

Authorizations:

basicAuth

query Parameters

decisionInstanceId	string Filter by decision instance id.
decisionInstanceIdIn	string Filter by decision instance ids. Must be a comma-separated list of decision instance ids.
decisionDefinitionId	string Filter by the decision definition the instances belongs to.
decisionDefinitionIdIn	string Filter by the decision definitions the instances belongs to. Must be a comma-separated list of decision definition ids.
decisionDefinitionKey	string Filter by the key of the decision definition the instances belongs to.
decisionDefinitionKeyIn	string Filter by the keys of the decision definition the instances belongs to. Must be a comma- separated list of decision definition keys.
decisionDefinitionName	string Filter by the name of the decision definition the instances belongs to.
decisionDefinitionNameLike	string Filter by the name of the decision definition the instances belongs to, that the parameter is a substring of.
processDefinitionId	string Filter by the process definition the instances belongs to.
processDefinitionKey	string Filter by the key of the process definition the instances belongs to.
processInstanceId	string Filter by the process instance the instances belongs to.
caseDefinitionId	string Filter by the case definition the instances belongs to.
caseDefinitionKey	string Filter by the key of the case definition the instances belongs to.
caseInstanceId	string Filter by the case instance the instances belongs to.
activityIdIn	string Filter by the activity ids the instances belongs to. Must be a comma-separated list of acitvity ids.
activityInstanceIdIn	string Filter by the activity instance ids the instances belongs to. Must be a comma-separated list of acitvity instance ids.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A historic decision instance must have one of the given tenant ids.
withoutTenantId	boolean Only include historic decision instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
evaluatedBefore	string <date-time> Restrict to instances that were evaluated before the given date. By default, the date must have the format `yyyy-MM- dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
evaluatedAfter	string <date-time> Restrict to instances that were evaluated after the given date. By default, the date must have the format `yyyy-MM- dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
userId	string Restrict to instances that were evaluated by the given user.
rootDecisionInstanceId	string Restrict to instances that have a given root decision instance id. This also includes the decision instance with the given id.
rootDecisionInstancesOnly	boolean Restrict to instances those are the root decision instance of an evaluation. Value may only be `true`, as `false` is the default behavior.
decisionRequirementsDefinitionId	string Filter by the decision requirements definition the instances belongs to.
decisionRequirementsDefinitionKey	string Filter by the key of the decision requirements definition the instances belongs to.
includeInputs	boolean Include input values in the result. Value may only be `true`, as `false` is the default behavior.
includeOutputs	boolean Include output values in the result. Value may only be `true`, as `false` is the default behavior.
disableBinaryFetching	boolean Disables fetching of byte array input and output values. Value may only be `true`, as `false` is the default behavior.
disableCustomObjectDeserialization	boolean Disables deserialization of input and output values that are custom objects. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "evaluationTime" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /history/decision-instance?includeInputs=true&includeOutputs=true

[{"activityId": "assignApprover",
"activityInstanceId": "assignApprover:67e9de1e-579d-11e5-9848-f0def1e59da8",
"collectResultValue": null,
"decisionDefinitionId": "invoice-assign-approver:1:4c864d79-579d-11e5-9848-f0def1e59da8",
"decisionDefinitionKey": "invoice-assign-approver",
"decisionDefinitionName": "Assign Approver",
"evaluationTime": "2015-09-10T11:22:06.000+0200",
"removalTime": null,
"id": "67ea2c3f-579d-11e5-9848-f0def1e59da8",
"inputs": [{"clauseId": "clause1",
"clauseName": "Invoice Amount",
"decisionInstanceId": "67ea2c3f-579d-11e5-9848-f0def1e59da8",
"errorMessage": null,
"id": "67ea2c41-579d-11e5-9848-f0def1e59da8",
"type": "Double",
"createTime": "2015-09-10T11:22:06.000+0200",
"removalTime": null,
"rootProcessInstanceId": "aRootProcessInstanceId",
"value": 123,
"valueInfo": { }
},
{"clauseId": "clause2",
"clauseName": "Invoice Category",
"decisionInstanceId": "67ea2c3f-579d-11e5-9848-f0def1e59da8",
"errorMessage": null,
"id": "67ea2c40-579d-11e5-9848-f0def1e59da8",
"type": "String",
"createTime": "2015-09-10T11:22:06.000+0200",
"removalTime": null,
"rootProcessInstanceId": "aRootProcessInstanceId",
"value": "Misc",
"valueInfo": { }
}
],
"outputs": [{"clauseId": "clause3",
"clauseName": "Approver Group",
"decisionInstanceId": "67ea2c3f-579d-11e5-9848-f0def1e59da8",
"errorMessage": null,
"id": "67ea2c42-579d-11e5-9848-f0def1e59da8",
"ruleId": "DecisionRule_1of5a87",
"ruleOrder": 1,
"type": "String",
"createTime": "2015-09-10T11:22:06.000+0200",
"removalTime": null,
"rootProcessInstanceId": "aRootProcessInstanceId",
"value": "accounting",
"valueInfo": { },
"variableName": "result"
}
],
"processDefinitionId": "invoice:1:4c6e3197-579d-11e5-9848-f0def1e59da8",
"processDefinitionKey": "invoice",
"processInstanceId": "67e98fec-579d-11e5-9848-f0def1e59da8",
"rootProcessInstanceId": "f8259e5d-ab9d-11e8-8449-e4a7a094a9d6",
"caseDefinitionId": null,
"caseDefinitionKey": null,
"caseInstanceId": null,
"tenantId": null,
"userId": null,
"rootDecisionInstanceId": null,
"decisionRequirementsDefinitionId": null,
"decisionRequirementsDefinitionKey": null
}
]

Get Historic Decision Instance Count

Queries for the number of historic decision instances that fulfill the given parameters. Takes the same parameters as the Get Historic Decision Instances method.

Authorizations:

basicAuth

query Parameters

decisionInstanceId	string Filter by decision instance id.
decisionInstanceIdIn	string Filter by decision instance ids. Must be a comma-separated list of decision instance ids.
decisionDefinitionId	string Filter by the decision definition the instances belongs to.
decisionDefinitionIdIn	string Filter by the decision definitions the instances belongs to. Must be a comma-separated list of decision definition ids.
decisionDefinitionKey	string Filter by the key of the decision definition the instances belongs to.
decisionDefinitionKeyIn	string Filter by the keys of the decision definition the instances belongs to. Must be a comma- separated list of decision definition keys.
decisionDefinitionName	string Filter by the name of the decision definition the instances belongs to.
decisionDefinitionNameLike	string Filter by the name of the decision definition the instances belongs to, that the parameter is a substring of.
processDefinitionId	string Filter by the process definition the instances belongs to.
processDefinitionKey	string Filter by the key of the process definition the instances belongs to.
processInstanceId	string Filter by the process instance the instances belongs to.
caseDefinitionId	string Filter by the case definition the instances belongs to.
caseDefinitionKey	string Filter by the key of the case definition the instances belongs to.
caseInstanceId	string Filter by the case instance the instances belongs to.
activityIdIn	string Filter by the activity ids the instances belongs to. Must be a comma-separated list of acitvity ids.
activityInstanceIdIn	string Filter by the activity instance ids the instances belongs to. Must be a comma-separated list of acitvity instance ids.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A historic decision instance must have one of the given tenant ids.
withoutTenantId	boolean Only include historic decision instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
evaluatedBefore	string <date-time> Restrict to instances that were evaluated before the given date. By default, the date must have the format `yyyy-MM- dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
evaluatedAfter	string <date-time> Restrict to instances that were evaluated after the given date. By default, the date must have the format `yyyy-MM- dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
userId	string Restrict to instances that were evaluated by the given user.
rootDecisionInstanceId	string Restrict to instances that have a given root decision instance id. This also includes the decision instance with the given id.
rootDecisionInstancesOnly	boolean Restrict to instances those are the root decision instance of an evaluation. Value may only be `true`, as `false` is the default behavior.
decisionRequirementsDefinitionId	string Filter by the decision requirements definition the instances belongs to.
decisionRequirementsDefinitionKey	string Filter by the key of the decision requirements definition the instances belongs to.

Responses

Response samples

200
400

Content type

application/json

{"count": 4
}

Delete Async (POST)

Delete multiple historic decision instances asynchronously (batch). At least historicDecisionInstanceIds or historicDecisionInstanceQuery has to be provided. If both are provided then all instances matching query criterion and instances from the list will be deleted.

Authorizations:

basicAuth

Request Body schema: application/json

historicDecisionInstanceIds	Array of strings or null A list of historic decision instance ids to delete.
	object (HistoricDecisionInstanceQueryDto) A historic decision instance query which defines a list of historic decision instances
deleteReason	string or null A string with delete reason.

Responses

Request samples

Payload

Content type

application/json

POST /history/decision-instance/delete

{"historicDecisionInstanceIds": ["aDecision",
"secondDecision"
],
"historicDecisionInstanceQuery": {"decisionDefinitionKey": "a-definition-key"
},
"deleteReason": "a delete reason"
}

Response samples

200
400

Content type

application/json

POST /history/decision-instance/delete

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"jobsCreated": 10,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"suspened": false,
"tenantId": null,
"createUserId": "aUser"
}

Set Removal Time Async (POST)

Sets the removal time to multiple historic decision instances asynchronously (batch).

At least historicDecisionInstanceIds or historicDecisionInstanceQuery has to be provided. If both are provided, all instances matching query criterion and instances from the list will be updated with a removal time.

Authorizations:

basicAuth

Request Body schema: application/json

hierarchical	boolean or null Sets the removal time to all historic decision instances in the hierarchy. Value may only be `true`, as `false` is the default behavior.
	object (HistoricDecisionInstanceQueryDto) A historic decision instance query which defines a list of historic decision instances
historicDecisionInstanceIds	Array of strings or null The ids of the historic decision instances to set the removal time for.
absoluteRemovalTime	string or null <date-time> The date for which the instances shall be removed. Value may not be `null`. Note: Cannot be set in conjunction with `clearedRemovalTime` or `calculatedRemovalTime`.
clearedRemovalTime	boolean or null Sets the removal time to `null`. Value may only be `true`, as `false` is the default behavior. Note: Cannot be set in conjunction with `absoluteRemovalTime` or `calculatedRemovalTime`.
calculatedRemovalTime	boolean or null The removal time is calculated based on the engine's configuration settings. Value may only be `true`, as `false` is the default behavior. Note: Cannot be set in conjunction with `absoluteRemovalTime` or `clearedRemovalTime`.

Responses

Request samples

Payload

Content type

application/json

POST /history/decision-instance/set-removal-time

{"absoluteRemovalTime": "2019-05-05T11:56:24.725+0200",
"hierarchical": true,
"historicDecisionInstanceQuery": {"evaluatedBefore": "2019-09-05T17:02:10.123+0200"
},
"historicDecisionInstanceIds": ["b4d2ad98-7240-11e9-98b7-be5e0f7575b7",
"b4d2ad94-7240-11e9-98b7-be5e0f7575b7"
]
}

Response samples

200
400

Content type

application/json

POST /history/decision-instance/set-removal-time

{"id": "120b568d-724a-11e9-98b7-be5e0f7575b7",
"type": "decision-set-removal-time",
"totalJobs": 12,
"batchJobsPerSeed": 100,
"jobsCreated": 10,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "120b5690-724a-11e9-98b7-be5e0f7575b7",
"monitorJobDefinitionId": "120b568f-724a-11e9-98b7-be5e0f7575b7",
"batchJobDefinitionId": "120b568e-724a-11e9-98b7-be5e0f7575b7",
"suspended": false,
"tenantId": "accounting",
"createUserId": "demo-user"
}

Get Historic Decision Instance

Retrieves a historic decision instance by id, according to the HistoricDecisionInstance interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the historic decision instance to be retrieved.

query Parameters

includeInputs	boolean Include input values in the result. Value may only be `true`, as `false` is the default behavior.
includeOutputs	boolean Include output values in the result. Value may only be `true`, as `false` is the default behavior.
disableBinaryFetching	boolean Disables fetching of byte array input and output values. Value may only be `true`, as `false` is the default behavior.
disableCustomObjectDeserialization	boolean Disables deserialization of input and output values that are custom objects. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
404

Content type

application/json

GET /history/decision-instance/aDecisionInstId?includeInput=true&includeOutputs=true

{"activityId": "assignApprover",
"activityInstanceId": "assignApprover:67e9de1e-579d-11e5-9848-f0def1e59da8",
"collectResultValue": null,
"decisionDefinitionId": "invoice-assign-approver:1:4c864d79-579d-11e5-9848-f0def1e59da8",
"decisionDefinitionKey": "invoice-assign-approver",
"decisionDefinitionName": "Assign Approver",
"evaluationTime": "2015-09-10T11:22:06.000+0200",
"removalTime": null,
"id": "67ea2c3f-579d-11e5-9848-f0def1e59da8",
"inputs": [{"clauseId": "clause1",
"clauseName": "Invoice Amount",
"decisionInstanceId": "67ea2c3f-579d-11e5-9848-f0def1e59da8",
"errorMessage": null,
"id": "67ea2c41-579d-11e5-9848-f0def1e59da8",
"type": "Double",
"createTime": "2015-09-10T11:22:06.000+0200",
"removalTime": null,
"rootProcessInstanceId": "aRootProcessInstanceId",
"value": 123,
"valueInfo": { }
},
{"clauseId": "clause2",
"clauseName": "Invoice Category",
"decisionInstanceId": "67ea2c3f-579d-11e5-9848-f0def1e59da8",
"errorMessage": null,
"id": "67ea2c40-579d-11e5-9848-f0def1e59da8",
"type": "String",
"createTime": "2015-09-10T11:22:06.000+0200",
"removalTime": null,
"rootProcessInstanceId": "aRootProcessInstanceId",
"value": "Misc",
"valueInfo": { }
}
],
"outputs": [{"clauseId": "clause3",
"clauseName": "Approver Group",
"decisionInstanceId": "67ea2c3f-579d-11e5-9848-f0def1e59da8",
"errorMessage": null,
"id": "67ea2c42-579d-11e5-9848-f0def1e59da8",
"ruleId": "DecisionRule_1of5a87",
"ruleOrder": 1,
"type": "String",
"createTime": "2015-09-10T11:22:06.000+0200",
"removalTime": null,
"rootProcessInstanceId": "aRootProcessInstanceId",
"value": "accounting",
"valueInfo": { },
"variableName": "result"
}
],
"processDefinitionId": "invoice:1:4c6e3197-579d-11e5-9848-f0def1e59da8",
"processDefinitionKey": "invoice",
"processInstanceId": "67e98fec-579d-11e5-9848-f0def1e59da8",
"rootProcessInstanceId": "f8259e5d-ab9d-11e8-8449-e4a7a094a9d6",
"caseDefinitionId": null,
"caseDefinitionKey": null,
"caseInstanceId": null,
"tenantId": null,
"userId": null,
"rootDecisionInstanceId": null,
"decisionRequirementsDefinitionId": null,
"decisionRequirementsDefinitionKey": null
}

Historic Decision Requirements Definition

Get DRD Statistics

Retrieves evaluation statistics of a given decision requirements definition.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the decision requirements definition.

query Parameters

decisionInstanceId

string

Restrict query results to be based only on specific evaluation instance of a given decision requirements definition.

Responses

Response samples

200
400

Content type

application/json

Example

request

GET /history/decision-requirements-definition/invoice:1:9f86d61f-9ee5-11e3-be3b-606720b6f99c/statistics

[{"decisionDefinitionKey": "dish-decision",
"evaluations": 1
}
]

Historic Detail

Get Historic Details

Queries for historic details that fulfill the given parameters. The size of the result set can be retrieved by using the Get Historic Detail Count method.

Authorizations:

basicAuth

query Parameters

processInstanceId	string Filter by process instance id.
processInstanceIdIn	string Only include historic details which belong to one of the passed comma-separated process instance ids.
executionId	string Filter by execution id.
taskId	string Filter by task id.
activityInstanceId	string Filter by activity instance id.
caseInstanceId	string Filter by case instance id.
caseExecutionId	string Filter by case execution id.
variableInstanceId	string Filter by variable instance id.
variableTypeIn	string Only include historic details where the variable updates belong to one of the passed comma-separated list of variable types. A list of all supported variable types can be found here. Note: All non-primitive variables are associated with the type `serializable`.
variableNameLike	string Filter by variable name like. Example usage: `variableNameLike(%camunda%)`. The query will match the names of variables in a case-insensitive way.
tenantIdIn	string Filter by a comma-separated list of tenant ids.
withoutTenantId	boolean Only include historic details that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
userOperationId	string Filter by a user operation id.
formFields	boolean Only include `HistoricFormFields`. Value may only be `true`, as `false` is the default behavior.
variableUpdates	boolean Only include `HistoricVariableUpdates`. Value may only be `true`, as `false` is the default behavior.
excludeTaskDetails	boolean Excludes all task-related `HistoricDetails`, so only items which have no task id set will be selected. When this parameter is used together with `taskId`, this call is ignored and task details are not excluded. Value may only be `true`, as `false` is the default behavior.
initial	boolean Restrict to historic variable updates that contain only initial variable values. Value may only be `true`, as `false` is the default behavior.
occurredBefore	string <date-time> Restrict to historic details that occured before the given date (including the date). Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.
occurredAfter	string <date-time> Restrict to historic details that occured after the given date (including the date). Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.
sortBy	string Enum: "processInstanceId" "variableName" "variableType" "variableRevision" "formPropertyId" "time" "occurrence" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
deserializeValues	boolean Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default `true`). If set to `true`, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to `false`, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML. Note: While `true` is the default value for reasons of backward compatibility, we recommend setting this parameter to `false` when developing web applications that are independent of the Java process applications deployed to the engine.

Responses

Response samples

200
400

Content type

application/json

GET /history/detail?processInstanceId=3cd597b7-001a-11e7-8c6b-34f39ab71d4e

[{"type": "variableUpdate",
"id": "3cd79390-001a-11e7-8c6b-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionId": "invoice:1:3c59899b-001a-11e7-8c6b-34f39ab71d4e",
"processInstanceId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"activityInstanceId": "StartEvent_1:3cd7456e-001a-11e7-8c6b-34f39ab71d4e",
"executionId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"caseDefinitionKey": null,
"caseDefinitionId": null,
"caseInstanceId": null,
"caseExecutionId": null,
"taskId": null,
"tenantId": null,
"userOperationId": "3cd76c7f-001a-11e7-8c6b-34f39ab71d4e",
"time": "2017-03-03T15:03:54.000+0200",
"variableName": "amount",
"variableInstanceId": "3cd65b08-001a-11e7-8c6b-34f39ab71d4e",
"variableType": "Double",
"value": 30,
"valueInfo": { },
"revision": 0,
"errorMessage": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"initial": true
},
{"type": "variableUpdate",
"id": "3cd79392-001a-11e7-8c6b-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionId": "invoice:1:3c59899b-001a-11e7-8c6b-34f39ab71d4e",
"processInstanceId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"activityInstanceId": "StartEvent_1:3cd7456e-001a-11e7-8c6b-34f39ab71d4e",
"executionId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"caseDefinitionKey": null,
"caseDefinitionId": null,
"caseInstanceId": null,
"caseExecutionId": null,
"taskId": null,
"tenantId": null,
"userOperationId": "3cd76c7f-001a-11e7-8c6b-34f39ab71d4e",
"time": "2017-03-03T15:03:54.000+0200",
"variableName": "invoiceDocument",
"variableInstanceId": "3cd65b0a-001a-11e7-8c6b-34f39ab71d4e",
"variableType": "File",
"value": null,
"valueInfo": {"mimeType": "application/pdf",
"filename": "invoice.pdf"
},
"revision": 0,
"errorMessage": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"initial": true
}
]

Get Historic Details (POST)

Queries for historic details that fulfill the given parameters. This method is slightly more powerful than the Get Historic Details method because it allows sorting by multiple parameters. The size of the result set can be retrieved by using the Get Historic Detail Count method.

Authorizations:

basicAuth

query Parameters

firstResult	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
deserializeValues	boolean Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default `true`). If set to `true`, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to `false`, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML. Note: While `true` is the default value for reasons of backward compatibility, we recommend setting this parameter to `false` when developing web applications that are independent of the Java process applications deployed to the engine.

Request Body schema: application/json

processInstanceId	string or null Filter by process instance id.
processInstanceIdIn	Array of strings or null Only include historic details which belong to one of the passed process instance ids.
executionId	string or null Filter by execution id.
taskId	string or null Filter by task id.
activityInstanceId	string or null Filter by activity instance id.
caseInstanceId	string or null Filter by case instance id.
caseExecutionId	string or null Filter by case execution id.
variableInstanceId	string or null Filter by variable instance id.
variableTypeIn	Array of strings or null Only include historic details where the variable updates belong to one of the passed list of variable types. A list of all supported variable types can be found here. Note: All non-primitive variables are associated with the type `serializable`.
variableNameLike	string or null Filter by variable name like. Example usage: `variableNameLike(%camunda%)`. The query will match the names of variables in a case-insensitive way.
tenantIdIn	Array of strings or null Filter by a list of tenant ids.
withoutTenantId	boolean or null Only include historic details that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
userOperationId	string or null Filter by a user operation id.
formFields	boolean or null Only include `HistoricFormFields`. Value may only be `true`, as `false` is the default behavior.
variableUpdates	boolean or null Only include `HistoricVariableUpdates`. Value may only be `true`, as `false` is the default behavior.
excludeTaskDetails	boolean or null Excludes all task-related `HistoricDetails`, so only items which have no task id set will be selected. When this parameter is used together with `taskId`, this call is ignored and task details are not excluded. Value may only be `true`, as `false` is the default behavior.
initial	boolean or null Restrict to historic variable updates that contain only initial variable values. Value may only be `true`, as `false` is the default behavior.
occurredBefore	string or null <date-time> Restrict to historic details that occured before the given date (including the date). Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.
occurredAfter	string or null <date-time> Restrict to historic details that occured after the given date (including the date). Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.
	Array of objects or null A JSON array of criteria to sort the result by. Each element of the array is a JSON object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Does not have an effect for the `count` endpoint.

Responses

Request samples

Payload

Content type

application/json

POST /history/detail?firstResult=1&maxResults=10

{"processInstanceId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"occurredAfter": "2018-01-29T10:15:45.000+0100",
"sorting": [{"sortBy": "processInstanceId",
"sortOrder": "asc"
}
]
}

Response samples

200
400

Content type

application/json

POST /history/detail?firstResult=1&maxResults=10

[{"type": "variableUpdate",
"id": "3cd79390-001a-11e7-8c6b-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionId": "invoice:1:3c59899b-001a-11e7-8c6b-34f39ab71d4e",
"processInstanceId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"activityInstanceId": "StartEvent_1:3cd7456e-001a-11e7-8c6b-34f39ab71d4e",
"executionId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"caseDefinitionKey": null,
"caseDefinitionId": null,
"caseInstanceId": null,
"caseExecutionId": null,
"taskId": null,
"tenantId": null,
"userOperationId": "3cd76c7f-001a-11e7-8c6b-34f39ab71d4e",
"time": "2017-03-03T15:03:54.000+0200",
"variableName": "amount",
"variableInstanceId": "3cd65b08-001a-11e7-8c6b-34f39ab71d4e",
"variableType": "Double",
"value": 30,
"valueInfo": { },
"revision": 0,
"errorMessage": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"initial": true
},
{"type": "variableUpdate",
"id": "3cd79392-001a-11e7-8c6b-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionId": "invoice:1:3c59899b-001a-11e7-8c6b-34f39ab71d4e",
"processInstanceId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"activityInstanceId": "StartEvent_1:3cd7456e-001a-11e7-8c6b-34f39ab71d4e",
"executionId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"caseDefinitionKey": null,
"caseDefinitionId": null,
"caseInstanceId": null,
"caseExecutionId": null,
"taskId": null,
"tenantId": null,
"userOperationId": "3cd76c7f-001a-11e7-8c6b-34f39ab71d4e",
"time": "2017-03-03T15:03:54.000+0200",
"variableName": "invoiceDocument",
"variableInstanceId": "3cd65b0a-001a-11e7-8c6b-34f39ab71d4e",
"variableType": "File",
"value": null,
"valueInfo": {"mimeType": "application/pdf",
"filename": "invoice.pdf"
},
"revision": 0,
"errorMessage": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"initial": true
}
]

Get Historic Detail Count

Queries for the number of historic details that fulfill the given parameters. Takes the same parameters as the Get Historic Details method.

Authorizations:

basicAuth

query Parameters

processInstanceId	string Filter by process instance id.
processInstanceIdIn	string Only include historic details which belong to one of the passed comma-separated process instance ids.
executionId	string Filter by execution id.
taskId	string Filter by task id.
activityInstanceId	string Filter by activity instance id.
caseInstanceId	string Filter by case instance id.
caseExecutionId	string Filter by case execution id.
variableInstanceId	string Filter by variable instance id.
variableTypeIn	string Only include historic details where the variable updates belong to one of the passed comma-separated list of variable types. A list of all supported variable types can be found here. Note: All non-primitive variables are associated with the type `serializable`.
variableNameLike	string Filter by variable name like. Example usage: `variableNameLike(%camunda%)`. The query will match the names of variables in a case-insensitive way.
tenantIdIn	string Filter by a comma-separated list of tenant ids.
withoutTenantId	boolean Only include historic details that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
userOperationId	string Filter by a user operation id.
formFields	boolean Only include `HistoricFormFields`. Value may only be `true`, as `false` is the default behavior.
variableUpdates	boolean Only include `HistoricVariableUpdates`. Value may only be `true`, as `false` is the default behavior.
excludeTaskDetails	boolean Excludes all task-related `HistoricDetails`, so only items which have no task id set will be selected. When this parameter is used together with `taskId`, this call is ignored and task details are not excluded. Value may only be `true`, as `false` is the default behavior.
initial	boolean Restrict to historic variable updates that contain only initial variable values. Value may only be `true`, as `false` is the default behavior.
occurredBefore	string <date-time> Restrict to historic details that occured before the given date (including the date). Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.
occurredAfter	string <date-time> Restrict to historic details that occured after the given date (including the date). Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.

Responses

Response samples

200
400

Content type

application/json

GET /history/detail/count?variableName=my_variable

{"count": 3
}

Get Historic Detail

Retrieves a historic detail by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the detail.

query Parameters

deserializeValue

boolean

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

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

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

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

Responses

Response samples

200
404

Content type

application/json

GET /history/detail/3cd79390-001a-11e7-8c6b-34f39ab71d4e

{"type": "variableUpdate",
"id": "3cd79390-001a-11e7-8c6b-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionId": "invoice:1:3c59899b-001a-11e7-8c6b-34f39ab71d4e",
"processInstanceId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"activityInstanceId": "StartEvent_1:3cd7456e-001a-11e7-8c6b-34f39ab71d4e",
"executionId": "3cd597b7-001a-11e7-8c6b-34f39ab71d4e",
"caseDefinitionKey": null,
"caseDefinitionId": null,
"caseInstanceId": null,
"caseExecutionId": null,
"taskId": null,
"tenantId": null,
"userOperationId": "3cd76c7f-001a-11e7-8c6b-34f39ab71d4e",
"time": "2017-03-03T15:03:54.000+0200",
"variableName": "amount",
"variableInstanceId": "3cd65b08-001a-11e7-8c6b-34f39ab71d4e",
"variableType": "Double",
"value": 30,
"valueInfo": { },
"revision": 0,
"errorMessage": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"initial": true
}

Get Historic Detail (Binary)

Retrieves the content of a historic variable update by id. Applicable for byte array and file variables.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the historic variable update.

Responses

Response samples

200
400
404

Content type

application/octet-stream

binary variable: Status 200. Content-Type: application/octet-stream

Historic External Task Log

Get External Task Logs

Queries for historic external task logs that fulfill the given parameters. The size of the result set can be retrieved by using the Get External Task Log Count method.

Authorizations:

basicAuth

query Parameters

logId	string Filter by historic external task log id.
externalTaskId	string Filter by external task id.
topicName	string Filter by an external task topic.
workerId	string Filter by the id of the worker that the task was most recently locked by.
errorMessage	string Filter by external task exception message.
activityIdIn	string Only include historic external task logs which belong to one of the passed activity ids.
activityInstanceIdIn	string Only include historic external task logs which belong to one of the passed activity instance ids.
executionIdIn	string Only include historic external task logs which belong to one of the passed execution ids.
processInstanceId	string Filter by process instance id.
processDefinitionId	string Filter by process definition id.
processDefinitionKey	string Filter by process definition key.
tenantIdIn	string Only include historic external task log entries which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean Only include historic external task log entries that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
priorityLowerThanOrEquals	integer <int64> Only include logs for which the associated external task had a priority lower than or equal to the given value. Value must be a valid `long` value.
priorityHigherThanOrEquals	integer <int64> Only include logs for which the associated external task had a priority higher than or equal to the given value. Value must be a valid `long` value.
creationLog	boolean Only include creation logs. Value may only be `true`, as `false` is the default behavior.
failureLog	boolean Only include failure logs. Value may only be `true`, as `false` is the default behavior.
successLog	boolean Only include success logs. Value may only be `true`, as `false` is the default behavior.
deletionLog	boolean Only include deletion logs. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "timestamp" "externalTaskId" "topicName" "workerId" "retries" "priority" "activityId" "activityInstanceId" "executionId" "processInstanceId" "processDefinitionId" "processDefinitionKey" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /history/external-task-log?externalTaskId=anExternalTaskId

[{"id": "someId",
"timestamp": "2017-01-15T15:22:20.000+0200",
"externalTaskId": "anExternalTaskId",
"topicName": "aTopicName",
"workerId": "aWorkerId",
"retries": 3,
"priority": 5,
"errorMessage": "An error occured!",
"activityId": "externalServiceTask",
"activityInstanceId": "externalServiceTask:15",
"executionId": "anExecutionId",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"tenantId": null,
"creationLog": false,
"failureLog": true,
"successLog": false,
"deletionLog": false,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Get External Task Logs (POST)

Queries for historic external task logs that fulfill the given parameters. This method is slightly more powerful than the Get External Task Logs method because it allows filtering by historic external task logs values of the different types String, Number or Boolean.

Authorizations:

basicAuth

Request Body schema: application/json

logId	string or null Filter by historic external task log id.
externalTaskId	string or null Filter by external task id.
topicName	string or null Filter by an external task topic.
workerId	string or null Filter by the id of the worker that the task was most recently locked by.
errorMessage	string or null Filter by external task exception message.
activityIdIn	Array of strings or null Only include historic external task logs which belong to one of the passed activity ids.
activityInstanceIdIn	Array of strings or null Only include historic external task logs which belong to one of the passed activity instance ids.
executionIdIn	Array of strings or null Only include historic external task logs which belong to one of the passed execution ids.
processInstanceId	string or null Filter by process instance id.
processDefinitionId	string or null Filter by process definition id.
processDefinitionKey	string or null Filter by process definition key.
tenantIdIn	Array of strings or null Only include historic external task log entries which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean or null Only include historic external task log entries that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
priorityLowerThanOrEquals	integer or null <int64> Only include logs for which the associated external task had a priority lower than or equal to the given value. Value must be a valid `long` value.
priorityHigherThanOrEquals	integer or null <int64> Only include logs for which the associated external task had a priority higher than or equal to the given value. Value must be a valid `long` value.
creationLog	boolean or null Only include creation logs. Value may only be `true`, as `false` is the default behavior.
failureLog	boolean or null Only include failure logs. Value may only be `true`, as `false` is the default behavior.
successLog	boolean or null Only include success logs. Value may only be `true`, as `false` is the default behavior.
deletionLog	boolean or null Only include deletion logs. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints.

Responses

Request samples

Payload

Content type

application/json

{"externalTaskId": "anExternalTaskId"
}

Response samples

200
400

Content type

application/json

POST /history/external-task-log

[{"id": "someId",
"timestamp": "2017-01-15T15:22:20.000+0200",
"externalTaskId": "anExternalTaskId",
"topicName": "aTopicName",
"workerId": "aWorkerId",
"retries": 3,
"priority": 5,
"errorMessage": "An error occured!",
"activityId": "externalServiceTask",
"activityInstanceId": "externalServiceTask:15",
"executionId": "anExecutionId",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"tenantId": null,
"creationLog": false,
"failureLog": true,
"successLog": false,
"deletionLog": false,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Get External Task Log Count

Queries for the number of historic external task logs that fulfill the given parameters. Takes the same parameters as the Get External Task Logs method.

Authorizations:

basicAuth

query Parameters

logId	string Filter by historic external task log id.
externalTaskId	string Filter by external task id.
topicName	string Filter by an external task topic.
workerId	string Filter by the id of the worker that the task was most recently locked by.
errorMessage	string Filter by external task exception message.
activityIdIn	string Only include historic external task logs which belong to one of the passed activity ids.
activityInstanceIdIn	string Only include historic external task logs which belong to one of the passed activity instance ids.
executionIdIn	string Only include historic external task logs which belong to one of the passed execution ids.
processInstanceId	string Filter by process instance id.
processDefinitionId	string Filter by process definition id.
processDefinitionKey	string Filter by process definition key.
tenantIdIn	string Only include historic external task log entries which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean Only include historic external task log entries that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
priorityLowerThanOrEquals	integer <int64> Only include logs for which the associated external task had a priority lower than or equal to the given value. Value must be a valid `long` value.
priorityHigherThanOrEquals	integer <int64> Only include logs for which the associated external task had a priority higher than or equal to the given value. Value must be a valid `long` value.
creationLog	boolean Only include creation logs. Value may only be `true`, as `false` is the default behavior.
failureLog	boolean Only include failure logs. Value may only be `true`, as `false` is the default behavior.
successLog	boolean Only include success logs. Value may only be `true`, as `false` is the default behavior.
deletionLog	boolean Only include deletion logs. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

GET /history/external-task-log/count?externalTaskId=anExternalTaskId

{"count": 1
}

Get External Task Log Count (POST)

Queries for the number of historic external task logs that fulfill the given parameters. This method takes the same message body as the Get External Task Logs (POST) method and therefore it is slightly more powerful than the Get External Task Log Count method.

Authorizations:

basicAuth

Request Body schema: application/json

logId	string or null Filter by historic external task log id.
externalTaskId	string or null Filter by external task id.
topicName	string or null Filter by an external task topic.
workerId	string or null Filter by the id of the worker that the task was most recently locked by.
errorMessage	string or null Filter by external task exception message.
activityIdIn	Array of strings or null Only include historic external task logs which belong to one of the passed activity ids.
activityInstanceIdIn	Array of strings or null Only include historic external task logs which belong to one of the passed activity instance ids.
executionIdIn	Array of strings or null Only include historic external task logs which belong to one of the passed execution ids.
processInstanceId	string or null Filter by process instance id.
processDefinitionId	string or null Filter by process definition id.
processDefinitionKey	string or null Filter by process definition key.
tenantIdIn	Array of strings or null Only include historic external task log entries which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean or null Only include historic external task log entries that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
priorityLowerThanOrEquals	integer or null <int64> Only include logs for which the associated external task had a priority lower than or equal to the given value. Value must be a valid `long` value.
priorityHigherThanOrEquals	integer or null <int64> Only include logs for which the associated external task had a priority higher than or equal to the given value. Value must be a valid `long` value.
creationLog	boolean or null Only include creation logs. Value may only be `true`, as `false` is the default behavior.
failureLog	boolean or null Only include failure logs. Value may only be `true`, as `false` is the default behavior.
successLog	boolean or null Only include success logs. Value may only be `true`, as `false` is the default behavior.
deletionLog	boolean or null Only include deletion logs. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints.

Responses

Request samples

Payload

Content type

application/json

{"externalTaskId": "anExternalTaskId"
}

Response samples

200
400

Content type

application/json

POST /history/external-task-log/count

{"count": 1
}

Get External Task Log

Retrieves a historic external task log by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the log entry.

Responses

Response samples

200
404

Content type

application/json

GET /history/external-task-log/someId

{"id": "someId",
"timestamp": "2017-01-15T15:22:20.000+0200",
"externalTaskId": "anExternalTaskId",
"topicName": "aTopicName",
"workerId": "aWorkerId",
"retries": 3,
"priority": 5,
"errorMessage": "An error occured!",
"activityId": "externalServiceTask",
"activityInstanceId": "externalServiceTask:15",
"executionId": "anExecutionId",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"tenantId": null,
"creationLog": false,
"failureLog": true,
"successLog": false,
"deletionLog": false,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}

Get External Task Log Error Details

Retrieves the corresponding error details of the passed historic external task log by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the historic external task log to get the error details for.

Responses

Response samples

200
404

Content type

text/plain

GET history/external-task-log/someId/error-details

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

Historic Identity Link Log

Get Identity Link Logs

Queries for historic identity link logs that fulfill given parameters. The size of the result set can be retrieved by using the Get Identity-Link-Log Count method.

Authorizations:

basicAuth

query Parameters

type	string Restricts to identity links that have the given type (candidate/assignee/owner).
userId	string Restricts to identity links that have the given user id.
groupId	string Restricts to identity links that have the given group id.
dateBefore	string <date-time> Restricts to identity links that have the time before the given time.
dateAfter	string <date-time> Restricts to identity links that have the time after the given time.
taskId	string Restricts to identity links that have the given task id.
processDefinitionId	string Restricts to identity links that have the given process definition id.
processDefinitionKey	string Restricts to identity links that have the given process definition key.
operationType	string Restricts to identity links that have the given operationType (add/delete).
assignerId	string Restricts to identity links that have the given assigner id.
tenantIdIn	string Filter by a comma-separated list of tenant ids.
withoutTenantId	boolean Only include historic identity links that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "time" "type" "userId" "groupId" "taskId" "processDefinitionId" "processDefinitionKey" "operationType" "assignerId" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /history/identity-link-log?taskId=aTaskId

[{"id": "1",
"time": "2014-03-01T08:00:00.000+0200",
"type": "candidate",
"userId": "aUserId",
"groupId": "aGroupId",
"taskId": "aTaskId",
"processDefinitionId": "12",
"operationType": "add",
"assignerId": "aAssignerId",
"processDefinitionKey": "oneTaskProcess",
"tenantId": "tenant1",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
},
{"id": "2",
"time": "2014-03-05T10:00:00.000+0200",
"type": "candidate",
"userId": "aUserId",
"groupId": "aGroupId",
"taskId": "aTaskId",
"processDefinitionId": "12",
"operationType": "delete",
"assignerId": "aAssignerId",
"processDefinitionKey": "oneTaskProcess",
"tenantId": "tenant1",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Get Identity Link Log Count

Queries for the number of historic identity link logs that fulfill the given parameters. Takes the same parameters as the Get Identity-Link-Logs method.

Authorizations:

basicAuth

query Parameters

type	string Restricts to identity links that have the given type (candidate/assignee/owner).
userId	string Restricts to identity links that have the given user id.
groupId	string Restricts to identity links that have the given group id.
dateBefore	string <date-time> Restricts to identity links that have the time before the given time.
dateAfter	string <date-time> Restricts to identity links that have the time after the given time.
taskId	string Restricts to identity links that have the given task id.
processDefinitionId	string Restricts to identity links that have the given process definition id.
processDefinitionKey	string Restricts to identity links that have the given process definition key.
operationType	string Restricts to identity links that have the given operationType (add/delete).
assignerId	string Restricts to identity links that have the given assigner id.
tenantIdIn	string Filter by a comma-separated list of tenant ids.
withoutTenantId	boolean Only include historic identity links that belong to no tenant. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

GET /history/identity-link-log/count?taskId=aTaskId

{"count": 2
}

Historic Incident

Get Incidents

Queries for historic incidents that fulfill given parameters. The size of the result set can be retrieved by using the Get Incident Count method.

Authorizations:

basicAuth

query Parameters

incidentId	string Restricts to incidents that have the given id.
incidentType	string Restricts to incidents that belong to the given incident type. See the User Guide for a list of incident types.
incidentMessage	string Restricts to incidents that have the given incident message.
incidentMessageLike	string Restricts to incidents that incidents message is a substring of the given value. The string can include the wildcard character '%' to express like-strategy: starts with (string%), ends with (%string) or contains (%string%).
processDefinitionId	string Restricts to incidents that belong to a process definition with the given id.
processDefinitionKey	string Restricts to incidents that have the given processDefinitionKey.
processDefinitionKeyIn	string Restricts to incidents that have one of the given process definition keys.
processInstanceId	string Restricts to incidents that belong to a process instance with the given id.
executionId	string Restricts to incidents that belong to an execution with the given id.
createTimeBefore	string <date-time> Restricts to incidents that have a createTime date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
createTimeAfter	string <date-time> Restricts to incidents that have a createTime date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
endTimeBefore	string <date-time> Restricts to incidents that have an endTimeBefore date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
endTimeAfter	string <date-time> Restricts to incidents that have an endTimeAfter date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
activityId	string Restricts to incidents that belong to an activity with the given id.
failedActivityId	string Restricts to incidents that were created due to the failure of an activity with the given id.
causeIncidentId	string Restricts to incidents that have the given incident id as cause incident.
rootCauseIncidentId	string Restricts to incidents that have the given incident id as root cause incident.
configuration	string Restricts to incidents that have the given parameter set as configuration.
historyConfiguration	string Restricts to incidents that have the given parameter set as history configuration.
open	boolean Restricts to incidents that are open.
resolved	boolean Restricts to incidents that are resolved.
deleted	boolean Restricts to incidents that are deleted.
tenantIdIn	string Restricts to incidents that have one of the given comma-separated tenant ids.
withoutTenantId	boolean Only include historic incidents that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
jobDefinitionIdIn	string Restricts to incidents that have one of the given comma-separated job definition ids.
sortBy	string Enum: "incidentId" "incidentMessage" "createTime" "endTime" "incidentType" "executionId" "activityId" "processInstanceId" "processDefinitionId" "processDefinitionKey" "causeIncidentId" "rootCauseIncidentId" "configuration" "historyConfiguration" "tenantId" "incidentState" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /history/incident?processInstanceId=aProcInstId

[{"id": "anIncidentId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anExecutionId",
"createTime": "2014-03-01T08:00:00.000+0200",
"endTime": null,
"incidentType": "failedJob",
"activityId": "serviceTask",
"failedActivityId": "serviceTask",
"causeIncidentId": "aCauseIncidentId",
"rootCauseIncidentId": "aRootCauseIncidentId",
"configuration": "aConfiguration",
"incidentMessage": "anIncidentMessage",
"tenantId": null,
"jobDefinitionId": "aJobDefinitionId",
"open": true,
"deleted": false,
"resolved": false,
"removalTime": null,
"rootProcessInstanceId": "aRootProcessInstanceId",
"annotation": "an annotation"
},
{"id": "anIncidentId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anotherExecutionId",
"createTime": "2014-03-01T08:00:00.000+0200",
"endTime": "2014-03-10T12:00:00.000+0200",
"incidentType": "customIncidentType",
"activityId": "userTask",
"failedActivityId": "userTask",
"causeIncidentId": "anotherCauseIncidentId",
"rootCauseIncidentId": "anotherRootCauseIncidentId",
"configuration": "anotherConfiguration",
"incidentMessage": "anotherIncidentMessage",
"tenantId": null,
"jobDefinitionId": null,
"open": false,
"deleted": false,
"resolved": true,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"annotation": "another annotation"
}
]

Get Incident Count

Queries for the number of historic incidents that fulfill the given parameters. Takes the same parameters as the Get Incidents method.

Authorizations:

basicAuth

query Parameters

incidentId	string Restricts to incidents that have the given id.
incidentType	string Restricts to incidents that belong to the given incident type. See the User Guide for a list of incident types.
incidentMessage	string Restricts to incidents that have the given incident message.
incidentMessageLike	string Restricts to incidents that incidents message is a substring of the given value. The string can include the wildcard character '%' to express like-strategy: starts with (string%), ends with (%string) or contains (%string%).
processDefinitionId	string Restricts to incidents that belong to a process definition with the given id.
processDefinitionKey	string Restricts to incidents that have the given processDefinitionKey.
processDefinitionKeyIn	string Restricts to incidents that have one of the given process definition keys.
processInstanceId	string Restricts to incidents that belong to a process instance with the given id.
executionId	string Restricts to incidents that belong to an execution with the given id.
createTimeBefore	string <date-time> Restricts to incidents that have a createTime date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
createTimeAfter	string <date-time> Restricts to incidents that have a createTime date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
endTimeBefore	string <date-time> Restricts to incidents that have an endTimeBefore date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
endTimeAfter	string <date-time> Restricts to incidents that have an endTimeAfter date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
activityId	string Restricts to incidents that belong to an activity with the given id.
failedActivityId	string Restricts to incidents that were created due to the failure of an activity with the given id.
causeIncidentId	string Restricts to incidents that have the given incident id as cause incident.
rootCauseIncidentId	string Restricts to incidents that have the given incident id as root cause incident.
configuration	string Restricts to incidents that have the given parameter set as configuration.
historyConfiguration	string Restricts to incidents that have the given parameter set as history configuration.
open	boolean Restricts to incidents that are open.
resolved	boolean Restricts to incidents that are resolved.
deleted	boolean Restricts to incidents that are deleted.
tenantIdIn	string Restricts to incidents that have one of the given comma-separated tenant ids.
withoutTenantId	boolean Only include historic incidents that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
jobDefinitionIdIn	string Restricts to incidents that have one of the given comma-separated job definition ids.

Responses

Response samples

200
400

Content type

application/json

GET /history/incident/count?processInstanceId=aProcInstId

{"count": 2
}

Historic Job Log

Get Job Logs

Queries for historic job logs that fulfill the given parameters. The size of the result set can be retrieved by using the Get Job Log Count method.

Authorizations:

basicAuth

query Parameters

logId	string Filter by historic job log id.
jobId	string Filter by job id.
jobExceptionMessage	string Filter by job exception message.
jobDefinitionId	string Filter by job definition id.
jobDefinitionType	string Filter by job definition type. See the User Guide for more information about job definition types.
jobDefinitionConfiguration	string Filter by job definition configuration.
activityIdIn	string Only include historic job logs which belong to one of the passed activity ids.
failedActivityIdIn	string Only include historic job logs which belong to failures of one of the passed activity ids.
executionIdIn	string Only include historic job logs which belong to one of the passed execution ids.
processInstanceId	string Filter by process instance id.
processDefinitionId	string Filter by process definition id.
processDefinitionKey	string Filter by process definition key.
deploymentId	string Filter by deployment id.
tenantIdIn	string Only include historic job log entries which belong to one of the passed and comma- separated tenant ids.
withoutTenantId	boolean Only include historic job log entries that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
hostname	string Filter by hostname.
jobPriorityLowerThanOrEquals	integer <int64> Only include logs for which the associated job had a priority lower than or equal to the given value. Value must be a valid `long` value.
jobPriorityHigherThanOrEquals	integer <int64> Only include logs for which the associated job had a priority higher than or equal to the given value. Value must be a valid `long` value.
creationLog	boolean Only include creation logs. Value may only be `true`, as `false` is the default behavior.
failureLog	boolean Only include failure logs. Value may only be `true`, as `false` is the default behavior.
successLog	boolean Only include success logs. Value may only be `true`, as `false` is the default behavior.
deletionLog	boolean Only include deletion logs. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "timestamp" "jobId" "jobDefinitionId" "jobDueDate" "jobRetries" "jobPriority" "activityId" "executionId" "processInstanceId" "processDefinitionId" "processDefinitionKey" "deploymentId" "hostname" "occurrence" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /history/job-log?jobId=aJobId

[{"id": "someId",
"timestamp": "2015-01-15T15:22:20.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"jobId": "aJobId",
"jobDefinitionId": "aJobDefinitionId",
"activityId": "serviceTask",
"jobType": "message",
"jobHandlerType": "async-continuation",
"jobDueDate": null,
"jobRetries": 3,
"jobPriority": 15,
"jobExceptionMessage": null,
"failedActivityId": null,
"executionId": "anExecutionId",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"deploymentId": "aDeploymentId",
"rootProcessInstanceId": "aRootProcessInstanceId",
"tenantId": null,
"hostname": "aHostname",
"batchId": "aBatchId",
"creationLog": true,
"failureLog": false,
"successLog": false,
"deletionLog": false
}
]

Get Job Logs (POST)

Queries for historic job logs that fulfill the given parameters. This method is slightly more powerful than the Get Job Logs method because it allows filtering by historic job logs values of the different types String, Number or Boolean.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

logId	string or null Filter by historic job log id.
jobId	string or null Filter by job id.
jobExceptionMessage	string or null Filter by job exception message.
jobDefinitionId	string or null Filter by job definition id.
jobDefinitionType	string or null Filter by job definition type. See the User Guide for more information about job definition types.
jobDefinitionConfiguration	string or null Filter by job definition configuration.
activityIdIn	Array of strings or null Only include historic job logs which belong to one of the passed activity ids.
failedActivityIdIn	Array of strings or null Only include historic job logs which belong to failures of one of the passed activity ids.
executionIdIn	Array of strings or null Only include historic job logs which belong to one of the passed execution ids.
processInstanceId	string or null Filter by process instance id.
processDefinitionId	string or null Filter by process definition id.
processDefinitionKey	string or null Filter by process definition key.
deploymentId	string or null Filter by deployment id.
tenantIdIn	Array of strings or null Only include historic job log entries which belong to one of the passed and comma- separated tenant ids.
withoutTenantId	boolean or null Only include historic job log entries that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
hostname	string or null Filter by hostname.
jobPriorityLowerThanOrEquals	integer or null <int64> Only include logs for which the associated job had a priority lower than or equal to the given value. Value must be a valid `long` value.
jobPriorityHigherThanOrEquals	integer or null <int64> Only include logs for which the associated job had a priority higher than or equal to the given value. Value must be a valid `long` value.
creationLog	boolean or null Only include creation logs. Value may only be `true`, as `false` is the default behavior.
failureLog	boolean or null Only include failure logs. Value may only be `true`, as `false` is the default behavior.
successLog	boolean or null Only include success logs. Value may only be `true`, as `false` is the default behavior.
deletionLog	boolean or null Only include deletion logs. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints

Responses

Request samples

Payload

Content type

application/json

{"jobId": "aJobId"
}

Response samples

200
400

Content type

application/json

POST /history/job-log

[{"id": "someId",
"timestamp": "2015-01-15T15:22:20.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"jobId": "aJobId",
"jobDefinitionId": "aJobDefinitionId",
"activityId": "serviceTask",
"jobType": "message",
"jobHandlerType": "async-continuation",
"jobDueDate": null,
"jobRetries": 3,
"jobPriority": 15,
"jobExceptionMessage": null,
"failedActivityId": null,
"executionId": "anExecutionId",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"deploymentId": "aDeploymentId",
"rootProcessInstanceId": "aRootProcessInstanceId",
"tenantId": null,
"hostname": "aHostname",
"batchId": "aBatchId",
"creationLog": true,
"failureLog": false,
"successLog": false,
"deletionLog": false
}
]

Get Job Log Count

Queries for the number of historic job logs that fulfill the given parameters. Takes the same parameters as the Get Job Logs method.

Authorizations:

basicAuth

query Parameters

logId	string Filter by historic job log id.
jobId	string Filter by job id.
jobExceptionMessage	string Filter by job exception message.
jobDefinitionId	string Filter by job definition id.
jobDefinitionType	string Filter by job definition type. See the User Guide for more information about job definition types.
jobDefinitionConfiguration	string Filter by job definition configuration.
activityIdIn	string Only include historic job logs which belong to one of the passed activity ids.
failedActivityIdIn	string Only include historic job logs which belong to failures of one of the passed activity ids.
executionIdIn	string Only include historic job logs which belong to one of the passed execution ids.
processInstanceId	string Filter by process instance id.
processDefinitionId	string Filter by process definition id.
processDefinitionKey	string Filter by process definition key.
deploymentId	string Filter by deployment id.
tenantIdIn	string Only include historic job log entries which belong to one of the passed and comma- separated tenant ids.
withoutTenantId	boolean Only include historic job log entries that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
hostname	string Filter by hostname.
jobPriorityLowerThanOrEquals	integer <int64> Only include logs for which the associated job had a priority lower than or equal to the given value. Value must be a valid `long` value.
jobPriorityHigherThanOrEquals	integer <int64> Only include logs for which the associated job had a priority higher than or equal to the given value. Value must be a valid `long` value.
creationLog	boolean Only include creation logs. Value may only be `true`, as `false` is the default behavior.
failureLog	boolean Only include failure logs. Value may only be `true`, as `false` is the default behavior.
successLog	boolean Only include success logs. Value may only be `true`, as `false` is the default behavior.
deletionLog	boolean Only include deletion logs. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

GET /history/job-log/count?jobId=aJobId

{"count": 1
}

Get Job Log Count (POST)

Queries for the number of historic job logs that fulfill the given parameters. This method takes the same message body as the Get Job Logs (POST) method and therefore it is slightly more powerful than the Get Job Log Count method.

Authorizations:

basicAuth

Request Body schema: application/json

logId	string or null Filter by historic job log id.
jobId	string or null Filter by job id.
jobExceptionMessage	string or null Filter by job exception message.
jobDefinitionId	string or null Filter by job definition id.
jobDefinitionType	string or null Filter by job definition type. See the User Guide for more information about job definition types.
jobDefinitionConfiguration	string or null Filter by job definition configuration.
activityIdIn	Array of strings or null Only include historic job logs which belong to one of the passed activity ids.
failedActivityIdIn	Array of strings or null Only include historic job logs which belong to failures of one of the passed activity ids.
executionIdIn	Array of strings or null Only include historic job logs which belong to one of the passed execution ids.
processInstanceId	string or null Filter by process instance id.
processDefinitionId	string or null Filter by process definition id.
processDefinitionKey	string or null Filter by process definition key.
deploymentId	string or null Filter by deployment id.
tenantIdIn	Array of strings or null Only include historic job log entries which belong to one of the passed and comma- separated tenant ids.
withoutTenantId	boolean or null Only include historic job log entries that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
hostname	string or null Filter by hostname.
jobPriorityLowerThanOrEquals	integer or null <int64> Only include logs for which the associated job had a priority lower than or equal to the given value. Value must be a valid `long` value.
jobPriorityHigherThanOrEquals	integer or null <int64> Only include logs for which the associated job had a priority higher than or equal to the given value. Value must be a valid `long` value.
creationLog	boolean or null Only include creation logs. Value may only be `true`, as `false` is the default behavior.
failureLog	boolean or null Only include failure logs. Value may only be `true`, as `false` is the default behavior.
successLog	boolean or null Only include success logs. Value may only be `true`, as `false` is the default behavior.
deletionLog	boolean or null Only include deletion logs. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints

Responses

Request samples

Payload

Content type

application/json

{"jobId": "aJobId"
}

Response samples

200
400

Content type

application/json

POST /history/job-log/count

{"count": 1
}

Get Job Log

Retrieves a historic job log by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the log entry.

Responses

Response samples

200
404

Content type

application/json

GET /history/job-log/someId

{"id": "someId",
"timestamp": "2015-01-15T15:22:20.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"jobId": "aJobId",
"jobDefinitionId": "aJobDefinitionId",
"activityId": "serviceTask",
"jobType": "message",
"jobHandlerType": "async-continuation",
"jobDueDate": null,
"jobRetries": 3,
"jobPriority": 15,
"jobExceptionMessage": null,
"failedActivityId": null,
"executionId": "anExecutionId",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"deploymentId": "aDeploymentId",
"rootProcessInstanceId": "aRootProcessInstanceId",
"tenantId": null,
"hostname": "aHostname",
"batchId": "aBatchId",
"creationLog": true,
"failureLog": false,
"successLog": false,
"deletionLog": false
}

Get Job Log Exception Stacktrace

Retrieves the corresponding exception stacktrace to the passed historic job log by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the historic job log to get the exception stacktrace for.

Responses

Response samples

200
404

Content type

text/plain

GET history/job-log/someId/stacktrace

                                   The result is the corresponding stacktrace as plain text.

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

Historic Process Definition

Get Cleanable Process Instance Report

Retrieves a report about a process definition and finished process instances relevant to history cleanup (see History cleanup) so that you can tune the history time to live. These reports include the count of the finished historic process instances, cleanable process instances and basic process definition data - id, key, name and version. The size of the result set can be retrieved by using the Get Cleanable Process Instance Report Count method.

Authorizations:

basicAuth

query Parameters

processDefinitionIdIn	string Filter by process definition ids. Must be a comma-separated list of process definition ids.
processDefinitionKeyIn	string Filter by process definition keys. Must be a comma-separated list of process definition keys.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A process definition must have one of the given tenant ids.
withoutTenantId	boolean Only include process definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
compact	boolean Only include process instances which have more than zero finished instances. Value may only be `true`, as `false` is the default behavior.
sortBy	string Value: "finished" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
500

Content type

application/json

GET /history/process-definition/cleanable-process-instance-report

[{"processDefinitionId": "invoice:1:7bf79f13-ef95-11e6-b6e6-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionName": "Invoice Receipt",
"processDefinitionVersion": 1,
"historyTimeToLive": 5,
"finishedProcessInstanceCount": 100,
"cleanableProcessInstanceCount": 53,
"tenantId": "aTenantId"
},
{"processDefinitionId": "invoice:2:7bf79f13-ef95-11e6-b6e6-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionName": "Invoice Receipt v2.0",
"processDefinitionVersion": 2,
"historyTimeToLive": 5,
"finishedProcessInstanceCount": 1000,
"cleanableProcessInstanceCount": 13,
"tenantId": "aTenantId"
}
]

Get Cleanable Process Instance Report Count

Queries for the number of report results about a process definition and finished process instances relevant to history cleanup (see History cleanup). Takes the same parameters as the Get Cleanable Process Instance Report method.

Authorizations:

basicAuth

query Parameters

processDefinitionIdIn	string Filter by process definition ids. Must be a comma-separated list of process definition ids.
processDefinitionKeyIn	string Filter by process definition keys. Must be a comma-separated list of process definition keys.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A process definition must have one of the given tenant ids.
withoutTenantId	boolean Only include process definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
compact	boolean Only include process instances which have more than zero finished instances. Value may only be `true`, as `false` is the default behavior.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/history/process-definition/cleanable-process-instance-report/count

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/history/process-definition/cleanable-process-instance-report/count

The API server with a custom url

/{url}/history/process-definition/cleanable-process-instance-report/count

Response samples

200
500

Content type

application/json

GET /history/process-definition/cleanable-process-instance-report/count

{"count": 1
}

Get Historic Activity Statistics

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition.

query Parameters

canceled	boolean Whether to include the number of canceled activity instances in the result or not. Valid values are `true` or `false`. Default: `false`.
finished	boolean Whether to include the number of finished activity instances in the result or not. Valid values are `true` or `false`. Default: `false`.
completeScope	boolean Whether to include the number of activity instances which completed a scope in the result or not. Valid values are `true` or `false`. Default: `false`.
incidents	boolean Whether to include the number of incidents. Valid values are `true` or `false`. Default: `false`.
startedBefore	string <date-time> Restrict to process instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Restrict to process instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string <date-time> Restrict to process instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string <date-time> Restrict to process instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
processInstanceIdIn	string Restrict to process instances with the given IDs. The IDs must be provided as a comma- separated list.
sortBy	string Value: "activityId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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.

Responses

Response samples

200
400

Content type

application/json

Example

Request With `canceled=true`

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

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

Historic Process Instance

Get List

Queries for historic process instances that fulfill the given parameters. The size of the result set can be retrieved by using the Get Process Instance Count method.

Authorizations:

basicAuth

query Parameters

sortBy	string Enum: "instanceId" "definitionId" "definitionKey" "definitionName" "definitionVersion" "businessKey" "startTime" "endTime" "duration" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
processInstanceId	string Filter by process instance id.
processInstanceIds	string Filter by process instance ids. Filter by a comma-separated list of `Strings`.
processDefinitionId	string Filter by the process definition the instances run on.
processDefinitionKey	string Filter by the key of the process definition the instances run on.
processDefinitionKeyIn	string Filter by a list of process definition keys. A process instance must have one of the given process definition keys. Filter by a comma-separated list of `Strings`.
processDefinitionName	string Filter by the name of the process definition the instances run on.
processDefinitionNameLike	string Filter by process definition names that the parameter is a substring of.
processDefinitionKeyNotIn	string Exclude instances that belong to a set of process definitions. Filter by a comma-separated list of `Strings`.
processInstanceBusinessKey	string Filter by process instance business key.
processInstanceBusinessKeyIn	string Filter by a list of business keys. A process instance must have one of the given business keys. Filter by a comma-separated list of `Strings`
processInstanceBusinessKeyLike	string Filter by process instance business key that the parameter is a substring of.
rootProcessInstances	boolean Restrict the query to all process instances that are top level process instances.
finished	boolean Only include finished process instances. This flag includes all process instances that are completed or terminated. Value may only be `true`, as `false` is the default behavior.
unfinished	boolean Only include unfinished process instances. Value may only be `true`, as `false` is the default behavior.
withIncidents	boolean Only include process instances which have an incident. Value may only be `true`, as `false` is the default behavior.
withRootIncidents	boolean Only include process instances which have a root incident. Value may only be `true`, as `false` is the default behavior.
incidentIdIn	string Restrict to instances that have an incident with one of the given ids. Filter by a comma-separated list of `Strings`
incidentType	string Filter by the incident type. See the User Guide for a list of incident types.
incidentStatus	string Enum: "open" "resolved" Only include process instances which have an incident in status either open or resolved. To get all process instances, use the query parameter withIncidents.
incidentMessage	string Filter by the incident message. Exact match.
incidentMessageLike	string Filter by the incident message that the parameter is a substring of.
startedBefore	string <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string <date-time> Restrict to instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string <date-time> Restrict to instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedActivityAfter	string <date-time> Restrict to instances that executed an activity after the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedActivityBefore	string <date-time> Restrict to instances that executed an activity before the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedJobAfter	string <date-time> Restrict to instances that executed an job after the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedJobBefore	string <date-time> Restrict to instances that executed an job before the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedBy	string Only include process instances that were started by the given user.
superProcessInstanceId	string Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstanceId	string Restrict query to one process instance that has a sub process instance with the given id.
superCaseInstanceId	string Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
subCaseInstanceId	string Restrict query to one process instance that has a sub case instance with the given id.
caseInstanceId	string Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
tenantIdIn	string Filter by a list of tenant ids. A process instance must have one of the given tenant ids. Filter by a comma-separated list of `Strings`
withoutTenantId	boolean Only include historic process instances which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
activityIdIn	string Restrict to instances with an active activity with one of the given ids. This filter behaves differently as `activeActivityIdIn` since it also yields results when filtering for activities with an incident. Filter by a comma-separated list of `Strings`
executedActivityIdIn	string Restrict to instances that executed an activity with one of given ids. Filter by a comma-separated list of `Strings`
activeActivityIdIn	string Restrict to instances that have an active activity with one of given ids. Filter by a comma-separated list of `Strings`
active	boolean Restrict to instances that are active.
suspended	boolean Restrict to instances that are suspended.
completed	boolean Restrict to instances that are completed.
externallyTerminated	boolean Restrict to instances that are externallyTerminated.
internallyTerminated	boolean Restrict to instances that are internallyTerminated.
variables	string Only include process instances that have/had variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. Key and value may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Match all variable names provided in variables case-insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match all variable values provided in variables case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.

Responses

Response samples

200
400

Content type

application/json

Response for GET /history/process-instance?finishedAfter=2013-01-01T00:00:00.000%2b0200&finishedBefore=2013-04-01T23:59:59.000%2b0200&executedActivityAfter=2013-03-23T13:42:44.000%2b0200

[{"id": "7c80cc8f-ef95-11e6-b6e6-34f39ab71d4e",
"businessKey": null,
"processDefinitionId": "invoice:1:7bf79f13-ef95-11e6-b6e6-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionName": "Invoice Receipt",
"processDefinitionVersion": 1,
"startTime": "2017-02-10T14:33:19.000+0200",
"endTime": null,
"removalTime": null,
"durationInMillis": null,
"startUserId": null,
"startActivityId": "StartEvent_1",
"deleteReason": null,
"rootProcessInstanceId": "f8259e5d-ab9d-11e8-8449-e4a7a094a9d6",
"superProcessInstanceId": null,
"superCaseInstanceId": null,
"caseInstanceId": null,
"tenantId": null,
"state": "ACTIVE",
"restartedProcessInstanceId": "2bef365d-3406-11ef-bd73-0a0027000003"
}
]

Get List (POST)

Queries for historic process instances that fulfill the given parameters. This method is slightly more powerful than the Get Process Instance because it allows filtering by multiple process variables of types String, Number or Boolean.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

processInstanceId	string or null Filter by process instance id.
processInstanceIds	Array of strings or null Filter by process instance ids. Must be a JSON array of `Strings`.
processDefinitionId	string or null Filter by the process definition the instances run on.
processDefinitionKey	string or null Filter by the key of the process definition the instances run on.
processDefinitionKeyIn	Array of strings or null Filter by a list of process definition keys. A process instance must have one of the given process definition keys. Must be a JSON array of `Strings`.
processDefinitionName	string or null Filter by the name of the process definition the instances run on.
processDefinitionNameLike	string or null Filter by process definition names that the parameter is a substring of.
processDefinitionKeyNotIn	Array of strings or null Exclude instances that belong to a set of process definitions. Must be a JSON array of `Strings`.
processInstanceBusinessKey	string or null Filter by process instance business key.
processInstanceBusinessKeyIn	Array of strings or null Filter by a list of business keys. A process instance must have one of the given business keys. Must be a JSON array of `Strings`
processInstanceBusinessKeyLike	string or null Filter by process instance business key that the parameter is a substring of.
rootProcessInstances	boolean or null Restrict the query to all process instances that are top level process instances.
finished	boolean or null Only include finished process instances. This flag includes all process instances that are completed or terminated. Value may only be `true`, as `false` is the default behavior.
unfinished	boolean or null Only include unfinished process instances. Value may only be `true`, as `false` is the default behavior.
withIncidents	boolean or null Only include process instances which have an incident. Value may only be `true`, as `false` is the default behavior.
withRootIncidents	boolean or null Only include process instances which have a root incident. Value may only be `true`, as `false` is the default behavior.
incidentIdIn	Array of strings or null Restrict to instances that have an incident with one of the given ids. Must be a JSON array of `Strings`
incidentType	string or null Filter by the incident type. See the User Guide for a list of incident types.
incidentStatus	string or null Enum: "open" "resolved" Only include process instances which have an incident in status either open or resolved. To get all process instances, use the query parameter withIncidents.
incidentMessage	string or null Filter by the incident message. Exact match.
incidentMessageLike	string or null Filter by the incident message that the parameter is a substring of.
startedBefore	string or null <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string or null <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string or null <date-time> Restrict to instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string or null <date-time> Restrict to instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedActivityAfter	string or null <date-time> Restrict to instances that executed an activity after the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedActivityBefore	string or null <date-time> Restrict to instances that executed an activity before the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedJobAfter	string or null <date-time> Restrict to instances that executed an job after the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedJobBefore	string or null <date-time> Restrict to instances that executed an job before the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedBy	string or null Only include process instances that were started by the given user.
superProcessInstanceId	string or null Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstanceId	string or null Restrict query to one process instance that has a sub process instance with the given id.
superCaseInstanceId	string or null Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
subCaseInstanceId	string or null Restrict query to one process instance that has a sub case instance with the given id.
caseInstanceId	string or null Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
tenantIdIn	Array of strings or null Filter by a list of tenant ids. A process instance must have one of the given tenant ids. Must be a JSON array of `Strings`
withoutTenantId	boolean or null Only include historic process instances which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
activityIdIn	Array of strings or null Restrict to instances with an active activity with one of the given ids. This filter behaves differently as `activeActivityIdIn` since it also yields results when filtering for activities with an incident. Must be a JSON array of `Strings`
executedActivityIdIn	Array of strings or null Restrict to instances that executed an activity with one of given ids. Must be a JSON array of `Strings`
activeActivityIdIn	Array of strings or null Restrict to instances that have an active activity with one of given ids. Must be a JSON array of `Strings`
active	boolean or null Restrict to instances that are active.
suspended	boolean or null Restrict to instances that are suspended.
completed	boolean or null Restrict to instances that are completed.
externallyTerminated	boolean or null Restrict to instances that are externallyTerminated.
internallyTerminated	boolean or null Restrict to instances that are internallyTerminated.
	Array of objects or null (VariableQueryParameterDto) A JSON array to only include process instances that have/had variables with certain values. The array consists of objects with the three properties `name`, `operator` and `value`. `name` (`String`) is the variable name, `operator` (`String`) is the comparison operator to be used and `value` the variable value. Value may be `String`, `Number` or `Boolean`. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`.
variableNamesIgnoreCase	boolean or null Match all variable names provided in variables case-insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match all variable values provided in variables case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
orQueries	Array of objects or null (HistoricProcessInstanceQueryDto) A JSON array of nested historic process instance queries with OR semantics. A process instance matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a process instance must fulfill at least one predicate of each query (Conjunctive Normal Form). All process instance query properties can be used except for: `sorting` See the User Guide for more information about OR queries.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

{"finishedAfter": "2013-01-01T00:00:00.000+0200",
"finishedBefore": "2013-04-01T23:59:59.000+0200",
"executedActivityAfter": "2013-03-23T13:42:44.000+0200",
"variables": [{"name": "myVariable",
"operator": "eq",
"value": "camunda"
},
{"name": "mySecondVariable",
"operator": "neq",
"value": 124
}
],
"sorting": [{"sortBy": "businessKey",
"sortOrder": "asc"
},
{"sortBy": "startTime",
"sortOrder": "desc"
}
]
}

Response samples

200
400

Content type

application/json

Response for POST /history/process-instance

[{"id": "7c80cc8f-ef95-11e6-b6e6-34f39ab71d4e",
"businessKey": null,
"processDefinitionId": "invoice:1:7bf79f13-ef95-11e6-b6e6-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionName": "Invoice Receipt",
"processDefinitionVersion": 1,
"startTime": "2017-02-10T14:33:19.000+0200",
"endTime": null,
"removalTime": null,
"durationInMillis": null,
"startUserId": null,
"startActivityId": "StartEvent_1",
"deleteReason": null,
"rootProcessInstanceId": "f8259e5d-ab9d-11e8-8449-e4a7a094a9d6",
"superProcessInstanceId": null,
"superCaseInstanceId": null,
"caseInstanceId": null,
"tenantId": null,
"state": "ACTIVE",
"restartedProcessInstanceId": "2bef365d-3406-11ef-bd73-0a0027000003"
}
]

Get List Count

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

Authorizations:

basicAuth

query Parameters

processInstanceId	string Filter by process instance id.
processInstanceIds	string Filter by process instance ids. Filter by a comma-separated list of `Strings`.
processDefinitionId	string Filter by the process definition the instances run on.
processDefinitionKey	string Filter by the key of the process definition the instances run on.
processDefinitionKeyIn	string Filter by a list of process definition keys. A process instance must have one of the given process definition keys. Filter by a comma-separated list of `Strings`.
processDefinitionName	string Filter by the name of the process definition the instances run on.
processDefinitionNameLike	string Filter by process definition names that the parameter is a substring of.
processDefinitionKeyNotIn	string Exclude instances that belong to a set of process definitions. Filter by a comma-separated list of `Strings`.
processInstanceBusinessKey	string Filter by process instance business key.
processInstanceBusinessKeyIn	string Filter by a list of business keys. A process instance must have one of the given business keys. Filter by a comma-separated list of `Strings`
processInstanceBusinessKeyLike	string Filter by process instance business key that the parameter is a substring of.
rootProcessInstances	boolean Restrict the query to all process instances that are top level process instances.
finished	boolean Only include finished process instances. This flag includes all process instances that are completed or terminated. Value may only be `true`, as `false` is the default behavior.
unfinished	boolean Only include unfinished process instances. Value may only be `true`, as `false` is the default behavior.
withIncidents	boolean Only include process instances which have an incident. Value may only be `true`, as `false` is the default behavior.
withRootIncidents	boolean Only include process instances which have a root incident. Value may only be `true`, as `false` is the default behavior.
incidentIdIn	string Restrict to instances that have an incident with one of the given ids. Filter by a comma-separated list of `Strings`
incidentType	string Filter by the incident type. See the User Guide for a list of incident types.
incidentStatus	string Enum: "open" "resolved" Only include process instances which have an incident in status either open or resolved. To get all process instances, use the query parameter withIncidents.
incidentMessage	string Filter by the incident message. Exact match.
incidentMessageLike	string Filter by the incident message that the parameter is a substring of.
startedBefore	string <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string <date-time> Restrict to instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string <date-time> Restrict to instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedActivityAfter	string <date-time> Restrict to instances that executed an activity after the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedActivityBefore	string <date-time> Restrict to instances that executed an activity before the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedJobAfter	string <date-time> Restrict to instances that executed an job after the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedJobBefore	string <date-time> Restrict to instances that executed an job before the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedBy	string Only include process instances that were started by the given user.
superProcessInstanceId	string Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstanceId	string Restrict query to one process instance that has a sub process instance with the given id.
superCaseInstanceId	string Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
subCaseInstanceId	string Restrict query to one process instance that has a sub case instance with the given id.
caseInstanceId	string Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
tenantIdIn	string Filter by a list of tenant ids. A process instance must have one of the given tenant ids. Filter by a comma-separated list of `Strings`
withoutTenantId	boolean Only include historic process instances which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
activityIdIn	string Restrict to instances with an active activity with one of the given ids. This filter behaves differently as `activeActivityIdIn` since it also yields results when filtering for activities with an incident. Filter by a comma-separated list of `Strings`
executedActivityIdIn	string Restrict to instances that executed an activity with one of given ids. Filter by a comma-separated list of `Strings`
activeActivityIdIn	string Restrict to instances that have an active activity with one of given ids. Filter by a comma-separated list of `Strings`
active	boolean Restrict to instances that are active.
suspended	boolean Restrict to instances that are suspended.
completed	boolean Restrict to instances that are completed.
externallyTerminated	boolean Restrict to instances that are externallyTerminated.
internallyTerminated	boolean Restrict to instances that are internallyTerminated.
variables	string Only include process instances that have/had variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. Key and value may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Match all variable names provided in variables case-insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match all variable values provided in variables case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.

Responses

Response samples

200
400

Content type

application/json

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

{"count": 1
}

Get List Count (POST)

Queries for the number of historic process instances that fulfill the given parameters. This method takes the same message body as the Get Process Instances (POST) method and therefore it is slightly more powerful than the Get Process Instance Count method.

Authorizations:

basicAuth

Request Body schema: application/json

processInstanceId	string or null Filter by process instance id.
processInstanceIds	Array of strings or null Filter by process instance ids. Must be a JSON array of `Strings`.
processDefinitionId	string or null Filter by the process definition the instances run on.
processDefinitionKey	string or null Filter by the key of the process definition the instances run on.
processDefinitionKeyIn	Array of strings or null Filter by a list of process definition keys. A process instance must have one of the given process definition keys. Must be a JSON array of `Strings`.
processDefinitionName	string or null Filter by the name of the process definition the instances run on.
processDefinitionNameLike	string or null Filter by process definition names that the parameter is a substring of.
processDefinitionKeyNotIn	Array of strings or null Exclude instances that belong to a set of process definitions. Must be a JSON array of `Strings`.
processInstanceBusinessKey	string or null Filter by process instance business key.
processInstanceBusinessKeyIn	Array of strings or null Filter by a list of business keys. A process instance must have one of the given business keys. Must be a JSON array of `Strings`
processInstanceBusinessKeyLike	string or null Filter by process instance business key that the parameter is a substring of.
rootProcessInstances	boolean or null Restrict the query to all process instances that are top level process instances.
finished	boolean or null Only include finished process instances. This flag includes all process instances that are completed or terminated. Value may only be `true`, as `false` is the default behavior.
unfinished	boolean or null Only include unfinished process instances. Value may only be `true`, as `false` is the default behavior.
withIncidents	boolean or null Only include process instances which have an incident. Value may only be `true`, as `false` is the default behavior.
withRootIncidents	boolean or null Only include process instances which have a root incident. Value may only be `true`, as `false` is the default behavior.
incidentIdIn	Array of strings or null Restrict to instances that have an incident with one of the given ids. Must be a JSON array of `Strings`
incidentType	string or null Filter by the incident type. See the User Guide for a list of incident types.
incidentStatus	string or null Enum: "open" "resolved" Only include process instances which have an incident in status either open or resolved. To get all process instances, use the query parameter withIncidents.
incidentMessage	string or null Filter by the incident message. Exact match.
incidentMessageLike	string or null Filter by the incident message that the parameter is a substring of.
startedBefore	string or null <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string or null <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string or null <date-time> Restrict to instances that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string or null <date-time> Restrict to instances that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedActivityAfter	string or null <date-time> Restrict to instances that executed an activity after the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedActivityBefore	string or null <date-time> Restrict to instances that executed an activity before the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedJobAfter	string or null <date-time> Restrict to instances that executed an job after the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
executedJobBefore	string or null <date-time> Restrict to instances that executed an job before the given date (inclusive). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedBy	string or null Only include process instances that were started by the given user.
superProcessInstanceId	string or null Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstanceId	string or null Restrict query to one process instance that has a sub process instance with the given id.
superCaseInstanceId	string or null Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
subCaseInstanceId	string or null Restrict query to one process instance that has a sub case instance with the given id.
caseInstanceId	string or null Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
tenantIdIn	Array of strings or null Filter by a list of tenant ids. A process instance must have one of the given tenant ids. Must be a JSON array of `Strings`
withoutTenantId	boolean or null Only include historic process instances which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
activityIdIn	Array of strings or null Restrict to instances with an active activity with one of the given ids. This filter behaves differently as `activeActivityIdIn` since it also yields results when filtering for activities with an incident. Must be a JSON array of `Strings`
executedActivityIdIn	Array of strings or null Restrict to instances that executed an activity with one of given ids. Must be a JSON array of `Strings`
activeActivityIdIn	Array of strings or null Restrict to instances that have an active activity with one of given ids. Must be a JSON array of `Strings`
active	boolean or null Restrict to instances that are active.
suspended	boolean or null Restrict to instances that are suspended.
completed	boolean or null Restrict to instances that are completed.
externallyTerminated	boolean or null Restrict to instances that are externallyTerminated.
internallyTerminated	boolean or null Restrict to instances that are internallyTerminated.
	Array of objects or null (VariableQueryParameterDto) A JSON array to only include process instances that have/had variables with certain values. The array consists of objects with the three properties `name`, `operator` and `value`. `name` (`String`) is the variable name, `operator` (`String`) is the comparison operator to be used and `value` the variable value. Value may be `String`, `Number` or `Boolean`. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`.
variableNamesIgnoreCase	boolean or null Match all variable names provided in variables case-insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match all variable values provided in variables case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
orQueries	Array of objects or null (HistoricProcessInstanceQueryDto) A JSON array of nested historic process instance queries with OR semantics. A process instance matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a process instance must fulfill at least one predicate of each query (Conjunctive Normal Form). All process instance query properties can be used except for: `sorting` See the User Guide for more information about OR queries.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

{"finishedAfter": "2013-01-01T00:00:00.000+0200",
"finishedBefore": "2013-04-01T23:59:59.000+0200",
"executedActivityAfter": "2013-03-23T13:42:44.000+0200",
"variables": [{"name": "myVariable",
"operator": "eq",
"value": "camunda"
},
{"name": "mySecondVariable",
"operator": "neq",
"value": 124
}
]
}

Response samples

200
400

Content type

application/json

{"count": 1
}

Delete Async (POST)

Delete multiple historic process instances asynchronously (batch). At least historicProcessInstanceIds or historicProcessInstanceQuery has to be provided. If both are provided then all instances matching query criterion and instances from the list will be deleted.

Authorizations:

basicAuth

Request Body schema: application/json

historicProcessInstanceIds	Array of strings or null A list historic process instance ids to delete.
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
deleteReason	string or null A string with delete reason.
failIfNotExists	boolean or null If set to `false`, the request will still be successful if one ore more of the process ids are not found.

Responses

Request samples

Payload

Content type

application/json

{"deleteReason": "aReason",
"historicProcessInstanceIds": ["aProcess",
"secondProcess"
],
"historicProcessInstanceQuery": {"startedAfter": "2016-10-11T11:44:13.000+0200",
"finishedBefore": "2016-10-13T11:44:17.000+0200"
}
}

Response samples

200
400

Content type

application/json

Response for POST /history/process-instance/delete

{"id": "120b568d-724a-11e9-98b7-be5e0f7575b7",
"type": "process-set-removal-time",
"totalJobs": 12,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "120b5690-724a-11e9-98b7-be5e0f7575b7",
"monitorJobDefinitionId": "120b568f-724a-11e9-98b7-be5e0f7575b7",
"batchJobDefinitionId": "120b568e-724a-11e9-98b7-be5e0f7575b7",
"tenantId": "accounting",
"suspended": false,
"createUserId": null
}

Get Duration Report

Retrieves a report about the duration of completed process instances, grouped by a period. These reports include the maximum, minimum and average duration of all completed process instances which were started in a given period.

Note: This only includes historic data.

Authorizations:

basicAuth

query Parameters

reportType required	string Mandatory. Specifies the type of the report to retrieve. To retrieve a report about the duration of process instances, the value must be set to `duration`.
periodUnit required	string Enum: "month" "quarter" Mandatory. Specifies the granularity of the report. Valid values are `month` and `quarter`.
processDefinitionIdIn	string Filter by process definition ids. Must be a comma-separated list of process definition ids.
processDefinitionKeyIn	string Filter by process definition keys. Must be a comma-separated list of process definition keys.
startedBefore	string <date-time> Restrict to instances that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2016-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Restrict to instances that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2016-01-23T14:42:45.000+0200`.

Responses

Response samples

200
400
403

Content type

application/json

[{"period": 1,
"periodUnit": "QUARTER",
"maximum": 500000,
"minimum": 250000,
"average": 375000
},
{"period": 2,
"periodUnit": "QUARTER",
"maximum": 600000,
"minimum": 300000,
"average": 450000
},
{"period": 3,
"periodUnit": "QUARTER",
"maximum": 1000000,
"minimum": 500000,
"average": 750000
},
{"period": 4,
"periodUnit": "QUARTER",
"maximum": 200000,
"minimum": 100000,
"average": 150000
}
]

Set Removal Time Async (POST)

Sets the removal time to multiple historic process instances asynchronously (batch).

At least historicProcessInstanceIds or historicProcessInstanceQuery has to be provided. If both are provided, all instances matching query criterion and instances from the list will be updated with a removal time.

Authorizations:

basicAuth

Request Body schema: application/json

historicProcessInstanceIds	Array of strings or null The id of the process instance.
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
hierarchical	boolean or null Sets the removal time to all historic process instances in the hierarchy. Value may only be `true`, as `false` is the default behavior.
updateInChunks	boolean or null Handles removal time updates in chunks, taking into account the defined size in `removalTimeUpdateChunkSize` in the process engine configuration. The size of the chunks can also be overridden per call with the `updateChunkSize` parameter. Enabling this option can lead to multiple executions of the resulting jobs, preventing the database transaction from timing out by limiting the number of rows to update. Value may only be `true`, as `false` is the default behavior.
updateChunkSize	integer or null <int32> Defines the size of the chunks in which removal time updates are processed. The value must be a positive integer between `1` and `500`. This only has an effect if `updateInChunks` is set to `true`. If undefined, the operation uses the `removalTimeUpdateChunkSize` defined in the process engine configuration.
absoluteRemovalTime	string or null <date-time> The date for which the instances shall be removed. Value may not be `null`. Note: Cannot be set in conjunction with `clearedRemovalTime` or `calculatedRemovalTime`.
clearedRemovalTime	boolean or null Sets the removal time to `null`. Value may only be `true`, as `false` is the default behavior. Note: Cannot be set in conjunction with `absoluteRemovalTime` or `calculatedRemovalTime`.
calculatedRemovalTime	boolean or null The removal time is calculated based on the engine's configuration settings. Value may only be `true`, as `false` is the default behavior. Note: Cannot be set in conjunction with `absoluteRemovalTime` or `clearedRemovalTime`.

Responses

Request samples

Payload

Content type

application/json

Example

POST `/history/process-instance/set-removal-time`

{"absoluteRemovalTime": "2019-05-05T11:56:24.725+0200",
"hierarchical": true,
"historicProcessInstanceQuery": {"unfinished": true
},
"historicProcessInstanceIds": ["b4d2ad98-7240-11e9-98b7-be5e0f7575b7",
"b4d2ad94-7240-11e9-98b7-be5e0f7575b7"
]
}

Response samples

200
400

Content type

application/json

Response for POST /history/process-instance/set-removal-time

{"id": "120b568d-724a-11e9-98b7-be5e0f7575b7",
"type": "process-set-removal-time",
"totalJobs": 12,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "120b5690-724a-11e9-98b7-be5e0f7575b7",
"monitorJobDefinitionId": "120b568f-724a-11e9-98b7-be5e0f7575b7",
"batchJobDefinitionId": "120b568e-724a-11e9-98b7-be5e0f7575b7",
"tenantId": "accounting",
"suspended": false,
"createUserId": null
}

Delete

Deletes a process instance from the history by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the historic process instance to be deleted.

query Parameters

failIfNotExists

boolean

If set to false, the request will still be successful if the process id is not found.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get

Retrieves a historic process instance by id, according to the HistoricProcessInstance interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the historic process instance to be retrieved.

Responses

Response samples

200
404

Content type

application/json

{"id": "7c80cc8f-ef95-11e6-b6e6-34f39ab71d4e",
"businessKey": null,
"processDefinitionId": "invoice:1:7bf79f13-ef95-11e6-b6e6-34f39ab71d4e",
"processDefinitionKey": "invoice",
"processDefinitionName": "Invoice Receipt",
"processDefinitionVersion": 1,
"startTime": "2017-02-10T14:33:19.000+0200",
"endTime": null,
"removalTime": null,
"durationInMillis": null,
"startUserId": null,
"startActivityId": "StartEvent_1",
"deleteReason": null,
"rootProcessInstanceId": "f8259e5d-ab9d-11e8-8449-e4a7a094a9d6",
"superProcessInstanceId": null,
"superCaseInstanceId": null,
"caseInstanceId": null,
"tenantId": null,
"state": "ACTIVE",
"restartedProcessInstanceId": "2bef365d-3406-11ef-bd73-0a0027000003"
}

Delete Variable Instances

Deletes all variables of a process instance from the history by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance for which all historic variables are to be deleted.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Historic Task Instance

Get Tasks (Historic)

Queries for historic tasks that fulfill the given parameters. The size of the result set can be retrieved by using the Get Task Count method.

Authorizations:

basicAuth

query Parameters

taskId	string Filter by task id.
taskParentTaskId	string Filter by parent task id.
processInstanceId	string Filter by process instance id.
rootProcessInstanceId	string Filter by root process instance id.
processInstanceBusinessKey	string Filter by process instance business key.
processInstanceBusinessKeyIn	string Filter by process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike	string Filter by process instance business key that has the parameter value as a substring.
executionId	string Filter by the id of the execution that executed the task.
processDefinitionId	string Filter by process definition id.
processDefinitionKey	string Restrict to tasks that belong to a process definition with the given key.
processDefinitionName	string Restrict to tasks that belong to a process definition with the given name.
caseInstanceId	string Filter by case instance id.
caseExecutionId	string Filter by the id of the case execution that executed the task.
caseDefinitionId	string Filter by case definition id.
caseDefinitionKey	string Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName	string Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn	string Only include tasks which belong to one of the passed comma-separated activity instance ids.
taskName	string Restrict to tasks that have the given name.
taskNameLike	string Restrict to tasks that have a name with the given parameter value as substring.
taskDescription	string Restrict to tasks that have the given description.
taskDescriptionLike	string Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey	string Restrict to tasks that have the given key.
taskDefinitionKeyIn	string Restrict to tasks that have one of the passed comma-separated task definition keys.
taskDeleteReason	string Restrict to tasks that have the given delete reason.
taskDeleteReasonLike	string Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee	string Restrict to tasks that the given user is assigned to.
taskAssigneeLike	string Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner	string Restrict to tasks that the given user owns.
taskOwnerLike	string Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority	integer <int32> Restrict to tasks that have the given priority.
assigned	boolean If set to `true`, restricts the query to all tasks that are assigned.
unassigned	boolean If set to `true`, restricts the query to all tasks that are unassigned.
finished	boolean Only include finished tasks. Value may only be `true`, as `false` is the default behavior.
unfinished	boolean Only include unfinished tasks. Value may only be `true`, as `false` is the default behavior.
processFinished	boolean Only include tasks of finished processes. Value may only be `true`, as `false` is the default behavior.
processUnfinished	boolean Only include tasks of unfinished processes. Value may only be `true`, as `false` is the default behavior.
taskDueDate	string <date-time> Restrict to tasks that are due on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskDueDateBefore	string <date-time> Restrict to tasks that are due before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskDueDateAfter	string <date-time> Restrict to tasks that are due after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
withoutTaskDueDate	boolean Only include tasks which have no due date. Value may only be `true`, as `false` is the default behavior.
taskFollowUpDate	string <date-time> Restrict to tasks that have a followUp date on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskFollowUpDateBefore	string <date-time> Restrict to tasks that have a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskFollowUpDateAfter	string <date-time> Restrict to tasks that have a followUp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedBefore	string <date-time> Restrict to tasks that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Restrict to tasks that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string <date-time> Restrict to tasks that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string <date-time> Restrict to tasks that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A task instance must have one of the given tenant ids.
withoutTenantId	boolean Only include historic task instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
taskVariables	string Only include tasks that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
processVariables	string Only include tasks that belong to process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`; `notLike`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Match the variable name provided in `taskVariables` and `processVariables` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match the variable value provided in `taskVariables` and `processVariables` case- insensitively. If set to `true` variableValue and variablevalue are treated as equal.
taskInvolvedUser	string Restrict to tasks with a historic identity link to the given user.
taskInvolvedGroup	string Restrict to tasks with a historic identity link to the given group.
taskHadCandidateUser	string Restrict to tasks with a historic identity link to the given candidate user.
taskHadCandidateGroup	string Restrict to tasks with a historic identity link to the given candidate group.
withCandidateGroups	boolean Only include tasks which have a candidate group. Value may only be `true`, as `false` is the default behavior.
withoutCandidateGroups	boolean Only include tasks which have no candidate group. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "taskId" "activityInstanceId" "processDefinitionId" "processInstanceId" "executionId" "duration" "endTime" "startTime" "taskName" "taskDescription" "assignee" "owner" "dueDate" "followUpDate" "deleteReason" "taskDefinitionKey" "priority" "caseDefinitionId" "caseInstanceId" "caseExecutionId" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

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

[{"id": "anId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anExecution",
"caseDefinitionId": "aCaseDefId",
"caseInstanceId": "aCaseInstId",
"caseExecutionId": "aCaseExecution",
"activityInstanceId": "anActInstId",
"name": "aName",
"description": "aDescription",
"deleteReason": "aDeleteReason",
"owner": "anOwner",
"assignee": "anAssignee",
"startTime": "2013-01-23T13:42:42.000+0200",
"endTime": "2013-01-23T13:45:42.000+0200",
"duration": 2000,
"taskDefinitionKey": "aTaskDefinitionKey",
"priority": 42,
"due": "2013-01-23T13:49:42.000+0200",
"parentTaskId": "aParentId",
"followUp:": "2013-01-23T13:44:42.000+0200",
"tenantId": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"taskState": "aTaskState"
}
]

Get Tasks (Historic) (POST)

Queries for historic tasks that fulfill the given parameters. This method is slightly more powerful than the Get Tasks (Historic) method because it allows filtering by multiple process or task variables of types String, Number or Boolean. The size of the result set can be retrieved by using the Get Task Count (POST) method.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

taskId	string or null Filter by task id.
taskParentTaskId	string or null Filter by parent task id.
processInstanceId	string or null Filter by process instance id.
rootProcessInstanceId	string or null Filter by root process instance id.
processInstanceBusinessKey	string or null Filter by process instance business key.
processInstanceBusinessKeyIn	Array of strings or null Filter by process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike	string or null Filter by process instance business key that has the parameter value as a substring.
executionId	string or null Filter by the id of the execution that executed the task.
processDefinitionId	string or null Filter by process definition id.
processDefinitionKey	string or null Restrict to tasks that belong to a process definition with the given key.
processDefinitionName	string or null Restrict to tasks that belong to a process definition with the given name.
caseInstanceId	string or null Filter by case instance id.
caseExecutionId	string or null Filter by the id of the case execution that executed the task.
caseDefinitionId	string or null Filter by case definition id.
caseDefinitionKey	string or null Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName	string or null Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn	Array of strings or null Only include tasks which belong to one of the passed activity instance ids.
taskName	string or null Restrict to tasks that have the given name.
taskNameLike	string or null Restrict to tasks that have a name with the given parameter value as substring.
taskDescription	string or null Restrict to tasks that have the given description.
taskDescriptionLike	string or null Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey	string or null Restrict to tasks that have the given key.
taskDefinitionKeyIn	Array of strings or null Restrict to tasks that have one of the passed task definition keys.
taskDeleteReason	string or null Restrict to tasks that have the given delete reason.
taskDeleteReasonLike	string or null Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee	string or null Restrict to tasks that the given user is assigned to.
taskAssigneeLike	string or null Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner	string or null Restrict to tasks that the given user owns.
taskOwnerLike	string or null Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority	integer or null <int32> Restrict to tasks that have the given priority.
assigned	boolean or null If set to `true`, restricts the query to all tasks that are assigned.
unassigned	boolean or null If set to `true`, restricts the query to all tasks that are unassigned.
finished	boolean or null Only include finished tasks. Value may only be `true`, as `false` is the default behavior.
unfinished	boolean or null Only include unfinished tasks. Value may only be `true`, as `false` is the default behavior.
processFinished	boolean or null Only include tasks of finished processes. Value may only be `true`, as `false` is the default behavior.
processUnfinished	boolean or null Only include tasks of unfinished processes. Value may only be `true`, as `false` is the default behavior.
taskDueDate	string or null <date-time> Restrict to tasks that are due on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskDueDateBefore	string or null <date-time> Restrict to tasks that are due before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskDueDateAfter	string or null <date-time> Restrict to tasks that are due after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
withoutTaskDueDate	boolean or null Only include tasks which have no due date. Value may only be `true`, as `false` is the default behavior.
taskFollowUpDate	string or null <date-time> Restrict to tasks that have a followUp date on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskFollowUpDateBefore	string or null <date-time> Restrict to tasks that have a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskFollowUpDateAfter	string or null <date-time> Restrict to tasks that have a followUp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedBefore	string or null <date-time> Restrict to tasks that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string or null <date-time> Restrict to tasks that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string or null <date-time> Restrict to tasks that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string or null <date-time> Restrict to tasks that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
tenantIdIn	Array of strings or null Filter by a list of tenant ids. A task instance must have one of the given tenant ids.
withoutTenantId	boolean or null Only include historic task instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null (VariableQueryParameterDto) Only include tasks that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
	Array of objects or null (VariableQueryParameterDto) Only include tasks that belong to process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`; `notLike`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean or null Match the variable name provided in `taskVariables` and `processVariables` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match the variable value provided in `taskVariables` and `processVariables` case- insensitively. If set to `true` variableValue and variablevalue are treated as equal.
taskInvolvedUser	string or null Restrict to tasks with a historic identity link to the given user.
taskInvolvedGroup	string or null Restrict to tasks with a historic identity link to the given group.
taskHadCandidateUser	string or null Restrict to tasks with a historic identity link to the given candidate user.
taskHadCandidateGroup	string or null Restrict to tasks with a historic identity link to the given candidate group.
withCandidateGroups	boolean or null Only include tasks which have a candidate group. Value may only be `true`, as `false` is the default behavior.
withoutCandidateGroups	boolean or null Only include tasks which have no candidate group. Value may only be `true`, as `false` is the default behavior.
orQueries	Array of objects or null (HistoricTaskInstanceQueryDto) A JSON array of nested historic task instance queries with OR semantics. A task instance matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a task instance must fulfill at least one predicate of each query (Conjunctive Normal Form). All task instance query properties can be used except for: `sorting`, `withCandidateGroups`, `withoutCandidateGroups`. See the User Guide for more information about OR queries.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints

Responses

Request samples

Payload

Content type

application/json

{"taskVariables": [{"name": "varName",
"value": "varValue",
"operator": "eq"
},
{"name": "anotherVarName",
"value": 30,
"operator": "neq"
}
],
"priority": 10,
"sorting": [{"sortBy": "priority",
"sortOrder": "asc"
},
{"sortBy": "duration",
"sortOrder": "desc"
}
]
}

Response samples

200
400

Content type

application/json

POST /history/task

[{"id": "anId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anExecution",
"caseDefinitionId": "aCaseDefId",
"caseInstanceId": "aCaseInstId",
"caseExecutionId": "aCaseExecution",
"activityInstanceId": "anActInstId",
"name": "aName",
"description": "aDescription",
"deleteReason": "aDeleteReason",
"owner": "anOwner",
"assignee": "anAssignee",
"startTime": "2013-01-23T13:42:42.000+0200",
"endTime": "2013-01-23T13:45:42.000+0200",
"duration": 2000,
"taskDefinitionKey": "aTaskDefinitionKey",
"priority": 10,
"due": "2013-01-23T13:49:42.000+0200",
"parentTaskId": "aParentId",
"followUp:": "2013-01-23T13:44:42.000+0200",
"tenantId": null,
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"taskState": "aTaskState"
}
]

Get Task Count

Queries for the number of historic tasks that fulfill the given parameters. Takes the same parameters as the Get Tasks (Historic) method.

Authorizations:

basicAuth

query Parameters

taskId	string Filter by task id.
taskParentTaskId	string Filter by parent task id.
processInstanceId	string Filter by process instance id.
rootProcessInstanceId	string Filter by root process instance id.
processInstanceBusinessKey	string Filter by process instance business key.
processInstanceBusinessKeyIn	string Filter by process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike	string Filter by process instance business key that has the parameter value as a substring.
executionId	string Filter by the id of the execution that executed the task.
processDefinitionId	string Filter by process definition id.
processDefinitionKey	string Restrict to tasks that belong to a process definition with the given key.
processDefinitionName	string Restrict to tasks that belong to a process definition with the given name.
caseInstanceId	string Filter by case instance id.
caseExecutionId	string Filter by the id of the case execution that executed the task.
caseDefinitionId	string Filter by case definition id.
caseDefinitionKey	string Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName	string Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn	string Only include tasks which belong to one of the passed comma-separated activity instance ids.
taskName	string Restrict to tasks that have the given name.
taskNameLike	string Restrict to tasks that have a name with the given parameter value as substring.
taskDescription	string Restrict to tasks that have the given description.
taskDescriptionLike	string Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey	string Restrict to tasks that have the given key.
taskDefinitionKeyIn	string Restrict to tasks that have one of the passed comma-separated task definition keys.
taskDeleteReason	string Restrict to tasks that have the given delete reason.
taskDeleteReasonLike	string Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee	string Restrict to tasks that the given user is assigned to.
taskAssigneeLike	string Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner	string Restrict to tasks that the given user owns.
taskOwnerLike	string Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority	integer <int32> Restrict to tasks that have the given priority.
assigned	boolean If set to `true`, restricts the query to all tasks that are assigned.
unassigned	boolean If set to `true`, restricts the query to all tasks that are unassigned.
finished	boolean Only include finished tasks. Value may only be `true`, as `false` is the default behavior.
unfinished	boolean Only include unfinished tasks. Value may only be `true`, as `false` is the default behavior.
processFinished	boolean Only include tasks of finished processes. Value may only be `true`, as `false` is the default behavior.
processUnfinished	boolean Only include tasks of unfinished processes. Value may only be `true`, as `false` is the default behavior.
taskDueDate	string <date-time> Restrict to tasks that are due on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskDueDateBefore	string <date-time> Restrict to tasks that are due before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskDueDateAfter	string <date-time> Restrict to tasks that are due after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
withoutTaskDueDate	boolean Only include tasks which have no due date. Value may only be `true`, as `false` is the default behavior.
taskFollowUpDate	string <date-time> Restrict to tasks that have a followUp date on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskFollowUpDateBefore	string <date-time> Restrict to tasks that have a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskFollowUpDateAfter	string <date-time> Restrict to tasks that have a followUp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedBefore	string <date-time> Restrict to tasks that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string <date-time> Restrict to tasks that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string <date-time> Restrict to tasks that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string <date-time> Restrict to tasks that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A task instance must have one of the given tenant ids.
withoutTenantId	boolean Only include historic task instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
taskVariables	string Only include tasks that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
processVariables	string Only include tasks that belong to process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`; `notLike`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Match the variable name provided in `taskVariables` and `processVariables` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match the variable value provided in `taskVariables` and `processVariables` case- insensitively. If set to `true` variableValue and variablevalue are treated as equal.
taskInvolvedUser	string Restrict to tasks with a historic identity link to the given user.
taskInvolvedGroup	string Restrict to tasks with a historic identity link to the given group.
taskHadCandidateUser	string Restrict to tasks with a historic identity link to the given candidate user.
taskHadCandidateGroup	string Restrict to tasks with a historic identity link to the given candidate group.
withCandidateGroups	boolean Only include tasks which have a candidate group. Value may only be `true`, as `false` is the default behavior.
withoutCandidateGroups	boolean Only include tasks which have no candidate group. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

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

{"count": 1
}

Get Task Count (POST)

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

Authorizations:

basicAuth

Request Body schema: application/json

taskId	string or null Filter by task id.
taskParentTaskId	string or null Filter by parent task id.
processInstanceId	string or null Filter by process instance id.
rootProcessInstanceId	string or null Filter by root process instance id.
processInstanceBusinessKey	string or null Filter by process instance business key.
processInstanceBusinessKeyIn	Array of strings or null Filter by process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike	string or null Filter by process instance business key that has the parameter value as a substring.
executionId	string or null Filter by the id of the execution that executed the task.
processDefinitionId	string or null Filter by process definition id.
processDefinitionKey	string or null Restrict to tasks that belong to a process definition with the given key.
processDefinitionName	string or null Restrict to tasks that belong to a process definition with the given name.
caseInstanceId	string or null Filter by case instance id.
caseExecutionId	string or null Filter by the id of the case execution that executed the task.
caseDefinitionId	string or null Filter by case definition id.
caseDefinitionKey	string or null Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName	string or null Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn	Array of strings or null Only include tasks which belong to one of the passed activity instance ids.
taskName	string or null Restrict to tasks that have the given name.
taskNameLike	string or null Restrict to tasks that have a name with the given parameter value as substring.
taskDescription	string or null Restrict to tasks that have the given description.
taskDescriptionLike	string or null Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey	string or null Restrict to tasks that have the given key.
taskDefinitionKeyIn	Array of strings or null Restrict to tasks that have one of the passed task definition keys.
taskDeleteReason	string or null Restrict to tasks that have the given delete reason.
taskDeleteReasonLike	string or null Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee	string or null Restrict to tasks that the given user is assigned to.
taskAssigneeLike	string or null Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner	string or null Restrict to tasks that the given user owns.
taskOwnerLike	string or null Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority	integer or null <int32> Restrict to tasks that have the given priority.
assigned	boolean or null If set to `true`, restricts the query to all tasks that are assigned.
unassigned	boolean or null If set to `true`, restricts the query to all tasks that are unassigned.
finished	boolean or null Only include finished tasks. Value may only be `true`, as `false` is the default behavior.
unfinished	boolean or null Only include unfinished tasks. Value may only be `true`, as `false` is the default behavior.
processFinished	boolean or null Only include tasks of finished processes. Value may only be `true`, as `false` is the default behavior.
processUnfinished	boolean or null Only include tasks of unfinished processes. Value may only be `true`, as `false` is the default behavior.
taskDueDate	string or null <date-time> Restrict to tasks that are due on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskDueDateBefore	string or null <date-time> Restrict to tasks that are due before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskDueDateAfter	string or null <date-time> Restrict to tasks that are due after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
withoutTaskDueDate	boolean or null Only include tasks which have no due date. Value may only be `true`, as `false` is the default behavior.
taskFollowUpDate	string or null <date-time> Restrict to tasks that have a followUp date on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskFollowUpDateBefore	string or null <date-time> Restrict to tasks that have a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
taskFollowUpDateAfter	string or null <date-time> Restrict to tasks that have a followUp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedBefore	string or null <date-time> Restrict to tasks that were started before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
startedAfter	string or null <date-time> Restrict to tasks that were started after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedBefore	string or null <date-time> Restrict to tasks that were finished before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
finishedAfter	string or null <date-time> Restrict to tasks that were finished after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
tenantIdIn	Array of strings or null Filter by a list of tenant ids. A task instance must have one of the given tenant ids.
withoutTenantId	boolean or null Only include historic task instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null (VariableQueryParameterDto) Only include tasks that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
	Array of objects or null (VariableQueryParameterDto) Only include tasks that belong to process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`; `notLike`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean or null Match the variable name provided in `taskVariables` and `processVariables` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match the variable value provided in `taskVariables` and `processVariables` case- insensitively. If set to `true` variableValue and variablevalue are treated as equal.
taskInvolvedUser	string or null Restrict to tasks with a historic identity link to the given user.
taskInvolvedGroup	string or null Restrict to tasks with a historic identity link to the given group.
taskHadCandidateUser	string or null Restrict to tasks with a historic identity link to the given candidate user.
taskHadCandidateGroup	string or null Restrict to tasks with a historic identity link to the given candidate group.
withCandidateGroups	boolean or null Only include tasks which have a candidate group. Value may only be `true`, as `false` is the default behavior.
withoutCandidateGroups	boolean or null Only include tasks which have no candidate group. Value may only be `true`, as `false` is the default behavior.
orQueries	Array of objects or null (HistoricTaskInstanceQueryDto) A JSON array of nested historic task instance queries with OR semantics. A task instance matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a task instance must fulfill at least one predicate of each query (Conjunctive Normal Form). All task instance query properties can be used except for: `sorting`, `withCandidateGroups`, `withoutCandidateGroups`. See the User Guide for more information about OR queries.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400

Content type

application/json

POST /history/task/count

{"count": 1
}

Get Task Report (Historic)

Retrieves a report of completed tasks. When the report type is set to count, the report contains a list of completed task counts where an entry contains the task name, the definition key of the task, the process definition id, the process definition key, the process definition name and the count of how many tasks were completed for the specified key in a given period. When the report type is set to duration, the report contains a minimum, maximum and average duration value of all completed task instances in a given period.

Authorizations:

basicAuth

query Parameters

reportType	string Enum: "duration" "count" Mandatory. Specifies the kind of the report to execute. To retrieve a report about the duration of process instances the value must be set to `duration`. For a report of the completed tasks in a specific timespan the value must be set to `count`.
periodUnit	string Enum: "MONTH" "QUARTER" When the report type is set to `duration`, this parameter is mandatory. Specifies the granularity of the report. Valid values are `month` and `quarter`.
completedBefore	string <date-time> Restrict to tasks that were completed before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
completedAfter	string <date-time> Restrict to tasks that were completed after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
groupBy	string When the report type is set to `count`, this parameter is mandatory. Groups the tasks report by a given criterion. Valid values are `taskName` and `processDefinition`.

Responses

Response samples

200
400

Content type

application/json

Example

Request for completed task report

GET /history/task/report?reportType=count&groupBy=processDefinition

[{"taskName": null,
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aProcessDefinitionKey",
"processDefinitionName": "A Process Definition Name",
"count": 42
},
{"taskName": null,
"processDefinitionId": "anotherProcessDefinitionId",
"processDefinitionKey": "anotherProcessDefinitionKey",
"processDefinitionName": "Another Process Definition Name",
"count": 9000
}
]

Historic User Operation Log

Get User Operation Log (Historic)

Queries for user operation log entries that fulfill the given parameters. The size of the result set can be retrieved by using the Get User Operation Log Count method.

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

Authorizations:

basicAuth

query Parameters

deploymentId	string Filter by deployment id.
processDefinitionId	string Filter by process definition id.
processDefinitionKey	string Filter by process definition key.
processInstanceId	string Filter by process instance id.
executionId	string Filter by execution id.
caseDefinitionId	string Filter by case definition id.
caseInstanceId	string Filter by case instance id.
caseExecutionId	string Filter by case execution id.
taskId	string Only include operations on this task.
externalTaskId	string Only include operations on this external task.
batchId	string Only include operations on this batch.
jobId	string Filter by job id.
jobDefinitionId	string Filter by job definition id.
userId	string Only include operations of this user.
operationId	string Filter by the id of the operation. This allows fetching of multiple entries which are part of a composite operation.
operationType	string Filter by the type of the operation like `Claim` or `Delegate`. See the Javadoc for a list of available operation types.
entityType	string Filter by the type of the entity that was affected by this operation, possible values are `Task`, `Attachment` or `IdentityLink`.
entityTypeIn	string Filter by a comma-separated list of types of the entities that was affected by this operation, possible values are `Task`, `Attachment` or `IdentityLink`.
category	string Filter by the category that this operation is associated with, possible values are `TaskWorker`, `Admin` or `Operator`.
categoryIn	string Filter by a comma-separated list of categories that this operation is associated with, possible values are `TaskWorker`, `Admin` or `Operator`.
property	string Only include operations that changed this property, e.g., `owner` or `assignee`.
afterTimestamp	string <date-time> Restrict to entries that were created after the given timestamp. By default, the timestamp must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.
beforeTimestamp	string <date-time> Restrict to entries that were created before the given timestamp. By default, the timestamp must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.
sortBy	string Value: "timestamp" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

Example

Gets an operation that updates a single task.

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

[{"id": "anUserOperationLogEntryId",
"deploymentId": "aDeploymentId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": null,
"processInstanceId": "aProcessInstanceId",
"executionId": "anExecutionId",
"taskId": "aTaskId",
"jobId": "aJobId",
"jobDefinitionId": "aJobDefinitionId",
"userId": "demo",
"timestamp": "2014-02-25T14:58:37.000+0200",
"operationId": "anOperationId",
"operationType": "Claim",
"entityType": "Task",
"property": "assignee",
"orgValue": null,
"newValue": "demo",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"category": "TaskWorker",
"annotation": "anAnnotation"
}
]

Get User Operation Log Count

Queries for the number of user operation log entries that fulfill the given parameters. Takes the same parameters as the Get User Operation Log (Historic) method.

Authorizations:

basicAuth

query Parameters

deploymentId	string Filter by deployment id.
processDefinitionId	string Filter by process definition id.
processDefinitionKey	string Filter by process definition key.
processInstanceId	string Filter by process instance id.
executionId	string Filter by execution id.
caseDefinitionId	string Filter by case definition id.
caseInstanceId	string Filter by case instance id.
caseExecutionId	string Filter by case execution id.
taskId	string Only include operations on this task.
externalTaskId	string Only include operations on this external task.
batchId	string Only include operations on this batch.
jobId	string Filter by job id.
jobDefinitionId	string Filter by job definition id.
userId	string Only include operations of this user.
operationId	string Filter by the id of the operation. This allows fetching of multiple entries which are part of a composite operation.
operationType	string Filter by the type of the operation like `Claim` or `Delegate`. See the Javadoc for a list of available operation types.
entityType	string Filter by the type of the entity that was affected by this operation, possible values are `Task`, `Attachment` or `IdentityLink`.
entityTypeIn	string Filter by a comma-separated list of types of the entities that was affected by this operation, possible values are `Task`, `Attachment` or `IdentityLink`.
category	string Filter by the category that this operation is associated with, possible values are `TaskWorker`, `Admin` or `Operator`.
categoryIn	string Filter by a comma-separated list of categories that this operation is associated with, possible values are `TaskWorker`, `Admin` or `Operator`.
property	string Only include operations that changed this property, e.g., `owner` or `assignee`.
afterTimestamp	string <date-time> Restrict to entries that were created after the given timestamp. By default, the timestamp must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.
beforeTimestamp	string <date-time> Restrict to entries that were created before the given timestamp. By default, the timestamp must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200.

Responses

Response samples

200
400

Content type

application/json

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

{"count": 1
}

Clear Annotation of an User Operation Log (Historic)

Clear the annotation which was previously set for auditing reasons.

Authorizations:

basicAuth

path Parameters

operationId

required

string

The operation id of the operation log to be updated.

Responses

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Annotation to an User Operation Log (Historic)

Set an annotation for auditing reasons.

Authorizations:

basicAuth

path Parameters

operationId

required

string

The operation id of the operation log to be updated.

Request Body schema: application/json

annotation

string or null

The annotation value to put.

Responses

Request samples

Payload

Content type

application/json

{"annotation": "Instances restarted due to wrong turn"
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Historic Variable Instance

Get Variable Instances

Queries for historic variable instances that fulfill the given parameters. The size of the result set can be retrieved by using the Get Variable Instance Count method.

Authorizations:

basicAuth

query Parameters

variableName	string Filter by variable name.
variableNameLike	string Restrict to variables with a name like the parameter.
variableValue	object Filter by variable value. Is treated as a `String` object on server side.
variableNamesIgnoreCase	boolean Match the variable name provided in `variableName` and `variableNameLike` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match the variable value provided in `variableValue` case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
variableTypeIn	string Only include historic variable instances which belong to one of the passed and comma- separated variable types. A list of all supported variable types can be found here. Note: All non-primitive variables are associated with the type 'serializable'.
includeDeleted	boolean Include variables that has already been deleted during the execution.
processInstanceId	string Filter by the process instance the variable belongs to.
processInstanceIdIn	string Only include historic variable instances which belong to one of the passed and comma-separated process instance ids.
processDefinitionId	string Filter by the process definition the variable belongs to.
processDefinitionKey	string Filter by a key of the process definition the variable belongs to.
executionIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated execution ids.
caseInstanceId	string Filter by the case instance the variable belongs to.
caseExecutionIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated case execution ids.
caseActivityIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated case activity ids.
taskIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated task ids.
activityInstanceIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated activity instance ids.
tenantIdIn	string Only include historic variable instances which belong to one of the passed and comma- separated tenant ids.
withoutTenantId	boolean Only include historic variable instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
variableNameIn	string Only include historic variable instances which belong to one of the passed and comma-separated variable names.
sortBy	string Enum: "instanceId" "variableName" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
deserializeValues	boolean Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default `true`). If set to `true`, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to `false`, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML. Note: While `true` is the default value for reasons of backward compatibility, we recommend setting this parameter to `false` when developing web applications that are independent of the Java process applications deployed to the engine.

Responses

Response samples

200
400

Content type

application/json

GET /history/variable-instance?variableName=my_variable

[{"id": "someId",
"name": "my_variable",
"type": "String",
"value": "my_value",
"valueInfo": { },
"processDefinitionKey": "aVariableInstanceProcDefKey",
"processDefinitionId": "aVariableInstanceProcDefId",
"processInstanceId": "aVariableInstanceProcInstId",
"executionId": "aVariableInstanceExecutionId",
"activityInstanceId": "aVariableInstanceActivityInstId",
"caseDefinitionKey": null,
"caseDefinitionId": null,
"caseInstanceId": null,
"caseExecutionId": null,
"taskId": null,
"tenantId": null,
"errorMessage": null,
"state": "CREATED",
"createTime": "2017-02-10T14:33:19.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Get Variable Instances (POST)

Queries for historic variable instances that fulfill the given parameters. This method is slightly more powerful than the Get Variable Instances method because it allows filtering by variable values of the different types String, Number or Boolean.

Authorizations:

basicAuth

query Parameters

firstResult	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
deserializeValues	boolean Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default `true`). If set to `true`, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to `false`, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML. Note: While `true` is the default value for reasons of backward compatibility, we recommend setting this parameter to `false` when developing web applications that are independent of the Java process applications deployed to the engine.

Request Body schema: application/json

variableName	string or null Filter by variable name.
variableNameLike	string or null Restrict to variables with a name like the parameter.
variableValue	object Filter by variable value. May be `String`, `Number` or `Boolean`.
variableNamesIgnoreCase	boolean or null Match the variable name provided in `variableName` and `variableNameLike` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match the variable value provided in `variableValue` case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
variableTypeIn	Array of strings or null Only include historic variable instances which belong to one of the passed and comma- separated variable types. A list of all supported variable types can be found here. Note: All non-primitive variables are associated with the type 'serializable'.
includeDeleted	boolean or null Include variables that has already been deleted during the execution.
processInstanceId	string or null Filter by the process instance the variable belongs to.
processInstanceIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed process instance ids.
processDefinitionId	string or null Filter by the process definition the variable belongs to.
processDefinitionKey	string or null Filter by a key of the process definition the variable belongs to.
executionIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and execution ids.
caseInstanceId	string or null Filter by the case instance the variable belongs to.
caseExecutionIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and case execution ids.
caseActivityIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and case activity ids.
taskIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and task ids.
activityInstanceIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and activity instance ids.
tenantIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and comma- separated tenant ids.
withoutTenantId	boolean or null Only include historic variable instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
variableNameIn	Array of strings or null Only include historic variable instances which belong to one of the passed variable names.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints

Responses

Request samples

Payload

Content type

application/json

{"variableName": "someVariable",
"variableValue": 42,
"sorting": [{"sortBy": "variableName",
"sortOrder": "asc"
},
{"sortBy": "instanceId",
"sortOrder": "desc"
}
]
}

Response samples

200
400

Content type

application/json

POST /history/variable-instance

[{"id": "someId",
"name": "someVariable",
"type": "Integer",
"variableType": "integer",
"value": 5,
"valueInfo": { },
"processDefinitionKey": "aProcessDefinitionKey",
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "aProcInstId",
"executionId": "aExecutionId",
"activityInstanceId": "aActivityInstId",
"caseDefinitionKey": null,
"caseDefinitionId": null,
"caseInstanceId": null,
"caseExecutionId": null,
"taskId": null,
"tenantId": null,
"errorMessage": null,
"state": "CREATED",
"createTime": "2017-02-10T14:33:19.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Get Variable Instance Count

Queries for the number of historic variable instances that fulfill the given parameters. Takes the same parameters as the Get Variable Instances method.

Authorizations:

basicAuth

query Parameters

variableName	string Filter by variable name.
variableNameLike	string Restrict to variables with a name like the parameter.
variableValue	object Filter by variable value. Is treated as a `String` object on server side.
variableNamesIgnoreCase	boolean Match the variable name provided in `variableName` and `variableNameLike` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match the variable value provided in `variableValue` case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
variableTypeIn	string Only include historic variable instances which belong to one of the passed and comma- separated variable types. A list of all supported variable types can be found here. Note: All non-primitive variables are associated with the type 'serializable'.
includeDeleted	boolean Include variables that has already been deleted during the execution.
processInstanceId	string Filter by the process instance the variable belongs to.
processInstanceIdIn	string Only include historic variable instances which belong to one of the passed and comma-separated process instance ids.
processDefinitionId	string Filter by the process definition the variable belongs to.
processDefinitionKey	string Filter by a key of the process definition the variable belongs to.
executionIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated execution ids.
caseInstanceId	string Filter by the case instance the variable belongs to.
caseExecutionIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated case execution ids.
caseActivityIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated case activity ids.
taskIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated task ids.
activityInstanceIdIn	string Only include historic variable instances which belong to one of the passed and and comma-separated activity instance ids.
tenantIdIn	string Only include historic variable instances which belong to one of the passed and comma- separated tenant ids.
withoutTenantId	boolean Only include historic variable instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
variableNameIn	string Only include historic variable instances which belong to one of the passed and comma-separated variable names.

Responses

Response samples

200
400

Content type

application/json

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

{"count": 1
}

Get Variable Instance Count (POST)

Queries for historic variable instances that fulfill the given parameters. This method takes the same message body as the Get Variable Instances (POST) method and therefore it is more powerful regarding variable values than the Get Variable Instance Count method.

Authorizations:

basicAuth

Request Body schema: application/json

variableName	string or null Filter by variable name.
variableNameLike	string or null Restrict to variables with a name like the parameter.
variableValue	object Filter by variable value. May be `String`, `Number` or `Boolean`.
variableNamesIgnoreCase	boolean or null Match the variable name provided in `variableName` and `variableNameLike` case- insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match the variable value provided in `variableValue` case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
variableTypeIn	Array of strings or null Only include historic variable instances which belong to one of the passed and comma- separated variable types. A list of all supported variable types can be found here. Note: All non-primitive variables are associated with the type 'serializable'.
includeDeleted	boolean or null Include variables that has already been deleted during the execution.
processInstanceId	string or null Filter by the process instance the variable belongs to.
processInstanceIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed process instance ids.
processDefinitionId	string or null Filter by the process definition the variable belongs to.
processDefinitionKey	string or null Filter by a key of the process definition the variable belongs to.
executionIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and execution ids.
caseInstanceId	string or null Filter by the case instance the variable belongs to.
caseExecutionIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and case execution ids.
caseActivityIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and case activity ids.
taskIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and task ids.
activityInstanceIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and activity instance ids.
tenantIdIn	Array of strings or null Only include historic variable instances which belong to one of the passed and comma- separated tenant ids.
withoutTenantId	boolean or null Only include historic variable instances that belong to no tenant. Value may only be `true`, as `false` is the default behavior.
variableNameIn	Array of strings or null Only include historic variable instances which belong to one of the passed variable names.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400

Content type

application/json

POST /history/variable-instance/count

{"count": 1
}

Delete Variable Instance

Deletes a historic variable instance by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the variable instance.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Variable Instance

Retrieves a historic variable by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the variable instance.

query Parameters

deserializeValues

boolean

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

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

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

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

Responses

Response samples

200
404

Content type

application/json

GET /history/variable-instance/someId

{"id": "someId",
"name": "amount",
"type": "Integer",
"value": 5,
"valueInfo": { },
"processDefinitionKey": "aProcessDefinitionKey",
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "aProcessInstanceId",
"executionId": "aExecutionId",
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726",
"caseDefinitionKey": null,
"caseDefinitionId": null,
"caseInstanceId": null,
"caseExecutionId": null,
"taskId": null,
"tenantId": null,
"errorMessage": null,
"state": "CREATED",
"createTime": "2017-02-10T14:33:19.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}

Get Variable Instance (Binary)

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the variable instance.

Responses

Response samples

200
400
404

Content type

application/octet-stream

For binary variables or files without any MIME type information, a byte stream is returned.

History Cleanup

Clean up history (POST)

Schedules asynchronous history cleanup (See History cleanup).

Note: This endpoint will return at most a single history cleanup job. Since version 7.9.0 it is possible to configure multiple parallel history cleanup jobs. Use GET /history/cleanup/jobs to find all the available history cleanup jobs.

Authorizations:

basicAuth

query Parameters

immediatelyDue

boolean

When true the job will be scheduled for nearest future. When false, the job will be scheduled for next batch window start time. Default is true.

Responses

Response samples

200
400

Content type

application/json

POST /history/cleanup?immediatelyDue=false

{"id": "074bd92a-1a95-11e7-8ceb-34f39ab71d4e",
"jobDefinitionId": null,
"processInstanceId": null,
"processDefinitionId": null,
"processDefinitionKey": null,
"executionId": null,
"exceptionMessage": null,
"retries": 3,
"dueDate": "2017-04-06T13:57:45.000+0200",
"suspended": false,
"priority": 0,
"tenantId": null,
"createTime": "2017-04-01T09:45:15.039+0100"
}

Get History Cleanup Configuration

Retrieves history cleanup batch window configuration (See History cleanup).

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

GET /history/cleanup/configuration

{"batchWindowStartTime": "2017-09-11T23:59:00.000+0200",
"batchWindowEndTime": "2017-09-12T02:00:00.000+0200",
"enabled": "true"
}

Find clean up history job (GET) Deprecated

Deprecated! Use GET /history/cleanup/jobs instead.

Finds history cleanup job (See History cleanup).

Authorizations:

basicAuth

Responses

Response samples

200
404

Content type

application/json

GET /history/cleanup/job

{"id": "074bd92a-1a95-11e7-8ceb-34f39ab71d4e",
"jobDefinitionId": null,
"processInstanceId": null,
"processDefinitionId": null,
"processDefinitionKey": null,
"executionId": null,
"exceptionMessage": null,
"retries": 3,
"dueDate": "2017-04-06T13:57:45.000+0200",
"suspended": false,
"priority": 0,
"tenantId": null,
"createTime": "2017-05-05T17:00:00+0200"
}

Find clean up history jobs (GET)

Finds history cleanup jobs (See History cleanup).

Authorizations:

basicAuth

Responses

Response samples

200
404

Content type

application/json

GET /history/cleanup/jobs

[{"id": "aJobId",
"jobDefinitionId": null,
"processInstanceId": null,
"processDefinitionId": null,
"processDefinitionKey": null,
"executionId": null,
"exceptionMessage": null,
"retries": 3,
"dueDate": "aDueDate",
"suspended": false,
"priority": 0,
"tenantId": null,
"createTime": "2018-05-05T17:00:00+0200"
},
{"id": "anotherJobId",
"jobDefinitionId": null,
"processInstanceId": null,
"processDefinitionId": null,
"processDefinitionKey": null,
"executionId": null,
"exceptionMessage": null,
"retries": 3,
"dueDate": "anotherDueDate",
"suspended": false,
"priority": 0,
"tenantId": null,
"createTime": "2018-05-05T17:00:00+0200"
}
]

Identity

Get a User's Groups

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

Authorizations:

basicAuth

query Parameters

userId

required

string

The id of the user to get the groups for.

Responses

Response samples

200
400

Content type

application/json

GET /identity/groups?userId=aUserId

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

Get Password Policy

A password policy consists of a list of rules that new passwords must follow to be policy compliant. This end point returns a JSON representation of the list of policy rules. More information on password policies in Camunda can be found in the password policy user guide and in the security instructions.

Authorizations:

basicAuth

Responses

Response samples

200
404

Content type

application/json

GET /identity/password-policy

{"rules": [{"placeholder": "PASSWORD_POLICY_USER_DATA",
"parameter": null
},
{"placeholder": "PASSWORD_POLICY_LENGTH",
"parameter": {"minLength": "10"
}
},
{"placeholder": "PASSWORD_POLICY_LOWERCASE",
"parameter": {"minLowerCase": "1"
}
},
{"placeholder": "PASSWORD_POLICY_UPPERCASE",
"parameter": {"minUpperCase": "1"
}
},
{"placeholder": "PASSWORD_POLICY_DIGIT",
"parameter": {"minDigit": "1"
}
},
{"placeholder": "PASSWORD_POLICY_SPECIAL",
"parameter": {"minSpecial": "1"
}
}
]
}

Validate Password

A password policy consists of a list of rules that new passwords must follow to be policy compliant. A password can be checked for compliancy via this end point. More information on password policies in Camunda can be found in the password policy user guide and in the security instructions.

Authorizations:

basicAuth

Request Body schema: application/json

password	string or null The candidate password to be check against the password policy.
	object (UserProfileDto)

Responses

Request samples

Payload

Content type

application/json

{"password": "myPassword",
"profile": {"id": "jonny1",
"firstName": "John",
"lastName": "Doe",
"email": "jonny@camunda.org"
}
}

Response samples

200
404

Content type

application/json

POST /identity/password-policy

{"rules": [{"placeholder": "PASSWORD_POLICY_USER_DATA",
"parameter": null,
"valid": true
},
{"placeholder": "PASSWORD_POLICY_LOWERCASE",
"parameter": {"minLowerCase": "1"
},
"valid": true
},
{"placeholder": "PASSWORD_POLICY_LENGTH",
"parameter": {"minLength": "10"
},
"valid": false
},
{"placeholder": "PASSWORD_POLICY_UPPERCASE\"",
"parameter": {"minUpperCase": "1"
},
"valid": false
},
{"placeholder": "PASSWORD_POLICY_DIGIT",
"parameter": {"minDigit": "1"
},
"valid": false
},
{"placeholder": "PASSWORD_POLICY_SPECIAL",
"parameter": {"minSpecial": "1"
},
"valid": false
}
],
"valid": false
}

Verify User

Verifies that user credentials are valid.

Authorizations:

basicAuth

Request Body schema: application/json

username	string or null The username of a user.
password	string or null A password of a user.

Responses

Request samples

Payload

Content type

application/json

{"username": "testUser",
"password": "testPassword"
}

Response samples

200
400

Content type

application/json

POST /identity/verify

{"authenticatedUser": "testUser",
"authenticated": true
}

Incident

Get List

Queries for incidents that fulfill given parameters. The size of the result set can be retrieved by using the Get Incident Count method.

Authorizations:

basicAuth

query Parameters

incidentId	string Restricts to incidents that have the given id.
incidentType	string Restricts to incidents that belong to the given incident type. See the User Guide for a list of incident types.
incidentMessage	string Restricts to incidents that have the given incident message.
incidentMessageLike	string Restricts to incidents that incidents message is a substring of the given value. The string can include the wildcard character '%' to express like-strategy: starts with (`string%`), ends with (`%string`) or contains (`%string%`).
processDefinitionId	string Restricts to incidents that belong to a process definition with the given id.
processDefinitionKeyIn	string Restricts to incidents that belong to a process definition with the given keys. Must be a comma-separated list.
processInstanceId	string Restricts to incidents that belong to a process instance with the given id.
executionId	string Restricts to incidents that belong to an execution with the given id.
incidentTimestampBefore	string <date-time> Restricts to incidents that have an incidentTimestamp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
incidentTimestampAfter	string <date-time> Restricts to incidents that have an incidentTimestamp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
activityId	string Restricts to incidents that belong to an activity with the given id.
failedActivityId	string Restricts to incidents that were created due to the failure of an activity with the given id.
causeIncidentId	string Restricts to incidents that have the given incident id as cause incident.
rootCauseIncidentId	string Restricts to incidents that have the given incident id as root cause incident.
configuration	string Restricts to incidents that have the given parameter set as configuration.
tenantIdIn	string Restricts to incidents that have one of the given comma-separated tenant ids.
jobDefinitionIdIn	string Restricts to incidents that have one of the given comma-separated job definition ids.
sortBy	string Enum: "incidentId" "incidentMessage" "incidentTimestamp" "incidentType" "executionId" "activityId" "processInstanceId" "processDefinitionId" "causeIncidentId" "rootCauseIncidentId" "configuration" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

[{"id": "anIncidentId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anExecutionId",
"incidentTimestamp": "2014-03-01T08:00:00.000+0200",
"incidentType": "failedJob",
"activityId": "serviceTask",
"failedActivityId": "serviceTask",
"causeIncidentId": "aCauseIncidentId",
"rootCauseIncidentId": "aRootCauseIncidentId",
"configuration": "aConfiguration",
"tenantId": null,
"incidentMessage": "anIncidentMessage",
"jobDefinitionId": "aJobDefinitionId",
"annotation": "an annotation"
},
{"id": "anIncidentId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anotherExecutionId",
"incidentTimestamp": "2014-03-01T09:00:00.000+0200",
"incidentType": "customIncidentType",
"activityId": "userTask",
"failedActivityId": "userTask",
"causeIncidentId": "anotherCauseIncidentId",
"rootCauseIncidentId": "anotherRootCauseIncidentId",
"configuration": "anotherConfiguration",
"tenantId": null,
"incidentMessage": "anotherIncidentMessage",
"jobDefinitionId": null,
"annotation": "another annotation"
}
]

Get List Count

Queries for the number of incidents that fulfill given parameters. Takes the same parameters as the Get Incidents method.

Authorizations:

basicAuth

query Parameters

incidentId	string Restricts to incidents that have the given id.
incidentType	string Restricts to incidents that belong to the given incident type. See the User Guide for a list of incident types.
incidentMessage	string Restricts to incidents that have the given incident message.
incidentMessageLike	string Restricts to incidents that incidents message is a substring of the given value. The string can include the wildcard character '%' to express like-strategy: starts with (`string%`), ends with (`%string`) or contains (`%string%`).
processDefinitionId	string Restricts to incidents that belong to a process definition with the given id.
processDefinitionKeyIn	string Restricts to incidents that belong to a process definition with the given keys. Must be a comma-separated list.
processInstanceId	string Restricts to incidents that belong to a process instance with the given id.
executionId	string Restricts to incidents that belong to an execution with the given id.
incidentTimestampBefore	string <date-time> Restricts to incidents that have an incidentTimestamp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
incidentTimestampAfter	string <date-time> Restricts to incidents that have an incidentTimestamp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
activityId	string Restricts to incidents that belong to an activity with the given id.
failedActivityId	string Restricts to incidents that were created due to the failure of an activity with the given id.
causeIncidentId	string Restricts to incidents that have the given incident id as cause incident.
rootCauseIncidentId	string Restricts to incidents that have the given incident id as root cause incident.
configuration	string Restricts to incidents that have the given parameter set as configuration.
tenantIdIn	string Restricts to incidents that have one of the given comma-separated tenant ids.
jobDefinitionIdIn	string Restricts to incidents that have one of the given comma-separated job definition ids.

Responses

Response samples

200
400

Content type

application/json

{"count": 2
}

Resolve Incident

Resolves an incident with given id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the incident to be resolved.

Responses

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Incident

Retrieves an incident by ID.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the incident to be retrieved.

Responses

Response samples

200
404

Content type

application/json

{"id": "anIncidentId",
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"executionId": "anExecutionId",
"incidentTimestamp": "2014-03-01T08:00:00.000+0200",
"incidentType": "failedJob",
"activityId": "serviceTask",
"failedActivityId": "serviceTask",
"causeIncidentId": "aCauseIncidentId",
"rootCauseIncidentId": "aRootCauseIncidentId",
"configuration": "aConfiguration",
"tenantId": null,
"incidentMessage": "anIncidentMessage",
"jobDefinitionId": "aJobDefinitionId",
"annotation": "an annotation"
}

Clear Incident Annotation

Clears the annotation of an incident with given id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the incident to clear the annotation at.

Responses

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Incident Annotation

Sets the annotation of an incident with given id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the incident to clear the annotation at.

Request Body schema: application/json

annotation

string or null

The annotation value to put.

Responses

Request samples

Payload

Content type

application/json

{"annotation": "my annotation"
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Job

Get Jobs

Queries for jobs that fulfill given parameters. The size of the result set can be retrieved by using the Get Job Count method.

Authorizations:

basicAuth

query Parameters

jobId	string Filter by job id.
jobIds	string Filter by a comma-separated list of job ids.
jobDefinitionId	string Only select jobs which exist for the given job definition.
processInstanceId	string Only select jobs which exist for the given process instance.
processInstanceIds	string Only select jobs which exist for the given comma-separated list of process instance ids.
executionId	string Only select jobs which exist for the given execution.
processDefinitionId	string Filter by the id of the process definition the jobs run on.
processDefinitionKey	string Filter by the key of the process definition the jobs run on.
activityId	string Only select jobs which exist for an activity with the given id.
withRetriesLeft	boolean Only select jobs which have retries left. Value may only be `true`, as `false` is the default behavior.
executable	boolean Only select jobs which are executable, i.e., retries > 0 and due date is `null` or due date is in the past. Value may only be `true`, as `false` is the default behavior.
timers	boolean Only select jobs that are timers. Cannot be used together with `messages`. Value may only be `true`, as `false` is the default behavior.
messages	boolean Only select jobs that are messages. Cannot be used together with `timers`. Value may only be `true`, as `false` is the default behavior.
dueDates	string Only select jobs where the due date is lower or higher than the given date. Due date expressions are comma-separated and are structured as follows: A valid condition value has the form `operator_value`. `operator` is the comparison operator to be used and `value` the date value as string. Valid operator values are: `gt` - greater than; `lt` - lower than. `value` may not contain underscore or comma characters.
createTimes	string Only select jobs created before or after the given date. Create time expressions are comma-separated and are structured as follows: A valid condition value has the form `operator_value`. `operator` is the comparison operator to be used and `value` the date value as string. Valid operator values are: `gt` - greater than; `lt` - lower than. `value` may not contain underscore or comma characters.
withException	boolean Only select jobs that failed due to an exception. Value may only be `true`, as `false` is the default behavior.
exceptionMessage	string Only select jobs that failed due to an exception with the given message.
failedActivityId	string Only select jobs that failed due to an exception at an activity with the given id.
noRetriesLeft	boolean Only select jobs which have no retries left. Value may only be `true`, as `false` is the default behavior.
active	boolean Only include active jobs. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Only include suspended jobs. Value may only be `true`, as `false` is the default behavior.
priorityLowerThanOrEquals	integer <int64> Only include jobs with a priority lower than or equal to the given value. Value must be a valid `long` value.
priorityHigherThanOrEquals	integer <int64> Only include jobs with a priority higher than or equal to the given value. Value must be a valid `long` value.
tenantIdIn	string Only include jobs which belong to one of the passed comma-separated tenant ids.
withoutTenantId	boolean Only include jobs which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeJobsWithoutTenantId	boolean Include jobs which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "jobId" "executionId" "processInstanceId" "processDefinitionId" "processDefinitionKey" "jobPriority" "jobRetries" "jobDueDate" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /job/count?dueDates=gt_2012-07-17T17:00:00.000+0200,lt_2012-07-17T18:00:00.000+0200&createTimes=gt_2012-05-05T10:00:00.000+0200,lt_2012-07-16T15:00:00.000+0200

[{"id": "aJobId",
"jobDefinitionId": "aJobDefinitionId",
"dueDate": "2018-07-17T17:05:00.000+0200",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aPDKey",
"executionId": "anExecutionId",
"retries": 0,
"exceptionMessage": "An exception Message",
"failedActivityId": "anActivityId",
"suspended": false,
"priority": 10,
"tenantId": null,
"createTime": "2018-05-05T17:00:00+0200",
"batchId": "aBatchId"
},
{"id": "anotherJobId",
"jobDefinitionId": "anotherJobDefinitionId",
"dueDate": "2018-07-17T17:55:00.000+0200",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "anotherPDId",
"processDefinitionKey": "anotherPDKey",
"executionId": "anotherExecutionId",
"retries": 0,
"exceptionMessage": "Another exception Message",
"failedActivityId": "anotherActivityId",
"suspended": true,
"priority": 8,
"tenantId": null,
"createTime": "2018-05-05T17:00:00+0200",
"batchId": null
}
]

Get Jobs (POST)

Queries for jobs that fulfill given parameters. This method is slightly more powerful than the Get Jobs method because it allows filtering by multiple jobs of types String, Number or Boolean.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

jobId	string or null Filter by job id.
jobIds	Array of strings or null Filter by a list of job ids.
jobDefinitionId	string or null Only select jobs which exist for the given job definition.
processInstanceId	string or null Only select jobs which exist for the given process instance.
processInstanceIds	Array of strings or null Only select jobs which exist for the given list of process instance ids.
executionId	string or null Only select jobs which exist for the given execution.
processDefinitionId	string or null Filter by the id of the process definition the jobs run on.
processDefinitionKey	string or null Filter by the key of the process definition the jobs run on.
activityId	string or null Only select jobs which exist for an activity with the given id.
withRetriesLeft	boolean or null Only select jobs which have retries left. Value may only be `true`, as `false` is the default behavior.
executable	boolean or null Only select jobs which are executable, i.e., retries > 0 and due date is `null` or due date is in the past. Value may only be `true`, as `false` is the default behavior.
timers	boolean or null Only select jobs that are timers. Cannot be used together with `messages`. Value may only be `true`, as `false` is the default behavior.
messages	boolean or null Only select jobs that are messages. Cannot be used together with `timers`. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null (JobConditionQueryParameterDto) Only select jobs where the due date is lower or higher than the given date.
	Array of objects or null (JobConditionQueryParameterDto) Only select jobs created before or after the given date.
withException	boolean or null Only select jobs that failed due to an exception. Value may only be `true`, as `false` is the default behavior.
exceptionMessage	string or null Only select jobs that failed due to an exception with the given message.
failedActivityId	string or null Only select jobs that failed due to an exception at an activity with the given id.
noRetriesLeft	boolean or null Only select jobs which have no retries left. Value may only be `true`, as `false` is the default behavior.
active	boolean or null Only include active jobs. Value may only be `true`, as `false` is the default behavior.
suspended	boolean or null Only include suspended jobs. Value may only be `true`, as `false` is the default behavior.
priorityLowerThanOrEquals	integer or null <int64> Only include jobs with a priority lower than or equal to the given value. Value must be a valid `long` value.
priorityHigherThanOrEquals	integer or null <int64> Only include jobs with a priority higher than or equal to the given value. Value must be a valid `long` value.
tenantIdIn	Array of strings or null Only include jobs which belong to one of the passed tenant ids.
withoutTenantId	boolean or null Only include jobs which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeJobsWithoutTenantId	boolean or null Include jobs which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Does not have an effect for the `count` endpoint.

Responses

Request samples

Payload

Content type

application/json

{"dueDates": [{"operator": "gt",
"value": "2018-07-17T17:00:00.000+0200"
},
{"operator": "lt",
"value": "2018-07-17T18:00:00.000+0200"
}
],
"createTimes": [{"operator": "gt",
"value": "2012-05-05T10:00:00.000+0200"
},
{"operator": "lt",
"value": "2012-07-16T15:00:00.000+0200"
}
],
"sorting": [{"sortBy": "jobDueDate",
"sortOrder": "asc"
},
{"sortBy": "jobRetries",
"sortOrder": "asc"
}
]
}

Response samples

200
400

Content type

application/json

POST /job

[{"id": "aJobId",
"jobDefinitionId": "aJobDefinitionId",
"dueDate": "2018-07-17T17:05:00.000+0200",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "aProcessDefinitionId",
"processDefinitionKey": "aPDKey",
"executionId": "anExecutionId",
"retries": 0,
"exceptionMessage": "An exception Message",
"failedActivityId": "anActivityId",
"suspended": false,
"priority": 10,
"tenantId": null,
"createTime": "2018-05-05T17:00:00+0200",
"batchId": "aBatchId"
},
{"id": "anotherJobId",
"jobDefinitionId": "anotherJobDefinitionId",
"dueDate": "2018-07-17T17:55:00.000+0200",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "anotherPDId",
"processDefinitionKey": "anotherPDKey",
"executionId": "anotherExecutionId",
"retries": 0,
"exceptionMessage": "Another exception Message",
"failedActivityId": "anotherActivityId",
"suspended": true,
"priority": 8,
"tenantId": null,
"createTime": "2018-05-05T17:00:00+0200",
"batchId": null
}
]

Get Job Count

Queries for the number of jobs that fulfill given parameters. Takes the same parameters as the Get Jobs method.

Authorizations:

basicAuth

query Parameters

jobId	string Filter by job id.
jobIds	string Filter by a comma-separated list of job ids.
jobDefinitionId	string Only select jobs which exist for the given job definition.
processInstanceId	string Only select jobs which exist for the given process instance.
processInstanceIds	string Only select jobs which exist for the given comma-separated list of process instance ids.
executionId	string Only select jobs which exist for the given execution.
processDefinitionId	string Filter by the id of the process definition the jobs run on.
processDefinitionKey	string Filter by the key of the process definition the jobs run on.
activityId	string Only select jobs which exist for an activity with the given id.
withRetriesLeft	boolean Only select jobs which have retries left. Value may only be `true`, as `false` is the default behavior.
executable	boolean Only select jobs which are executable, i.e., retries > 0 and due date is `null` or due date is in the past. Value may only be `true`, as `false` is the default behavior.
timers	boolean Only select jobs that are timers. Cannot be used together with `messages`. Value may only be `true`, as `false` is the default behavior.
messages	boolean Only select jobs that are messages. Cannot be used together with `timers`. Value may only be `true`, as `false` is the default behavior.
dueDates	string Only select jobs where the due date is lower or higher than the given date. Due date expressions are comma-separated and are structured as follows: A valid condition value has the form `operator_value`. `operator` is the comparison operator to be used and `value` the date value as string. Valid operator values are: `gt` - greater than; `lt` - lower than. `value` may not contain underscore or comma characters.
createTimes	string Only select jobs created before or after the given date. Create time expressions are comma-separated and are structured as follows: A valid condition value has the form `operator_value`. `operator` is the comparison operator to be used and `value` the date value as string. Valid operator values are: `gt` - greater than; `lt` - lower than. `value` may not contain underscore or comma characters.
withException	boolean Only select jobs that failed due to an exception. Value may only be `true`, as `false` is the default behavior.
exceptionMessage	string Only select jobs that failed due to an exception with the given message.
failedActivityId	string Only select jobs that failed due to an exception at an activity with the given id.
noRetriesLeft	boolean Only select jobs which have no retries left. Value may only be `true`, as `false` is the default behavior.
active	boolean Only include active jobs. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Only include suspended jobs. Value may only be `true`, as `false` is the default behavior.
priorityLowerThanOrEquals	integer <int64> Only include jobs with a priority lower than or equal to the given value. Value must be a valid `long` value.
priorityHigherThanOrEquals	integer <int64> Only include jobs with a priority higher than or equal to the given value. Value must be a valid `long` value.
tenantIdIn	string Only include jobs which belong to one of the passed comma-separated tenant ids.
withoutTenantId	boolean Only include jobs which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeJobsWithoutTenantId	boolean Include jobs which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

GET /job/count?dueDates=gt_2012-07-17T17:00:00.000+0200,lt_2012-07-17T18:00:00.000+0200&createTimes=gt_2012-05-05T10:00:00.000+0200,lt_2012-07-16T15:00:00.000+0200

{"count": 2
}

Get Job Count (POST)

Queries for jobs that fulfill given parameters. This method takes the same message body as the [Get Jobs POST](https://docs.camunda.org/manual/7.22/reference/rest/job/post- query/) method and therefore it is slightly more powerful than the Get Job Count method.

Authorizations:

basicAuth

Request Body schema: application/json

jobId	string or null Filter by job id.
jobIds	Array of strings or null Filter by a list of job ids.
jobDefinitionId	string or null Only select jobs which exist for the given job definition.
processInstanceId	string or null Only select jobs which exist for the given process instance.
processInstanceIds	Array of strings or null Only select jobs which exist for the given list of process instance ids.
executionId	string or null Only select jobs which exist for the given execution.
processDefinitionId	string or null Filter by the id of the process definition the jobs run on.
processDefinitionKey	string or null Filter by the key of the process definition the jobs run on.
activityId	string or null Only select jobs which exist for an activity with the given id.
withRetriesLeft	boolean or null Only select jobs which have retries left. Value may only be `true`, as `false` is the default behavior.
executable	boolean or null Only select jobs which are executable, i.e., retries > 0 and due date is `null` or due date is in the past. Value may only be `true`, as `false` is the default behavior.
timers	boolean or null Only select jobs that are timers. Cannot be used together with `messages`. Value may only be `true`, as `false` is the default behavior.
messages	boolean or null Only select jobs that are messages. Cannot be used together with `timers`. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null (JobConditionQueryParameterDto) Only select jobs where the due date is lower or higher than the given date.
	Array of objects or null (JobConditionQueryParameterDto) Only select jobs created before or after the given date.
withException	boolean or null Only select jobs that failed due to an exception. Value may only be `true`, as `false` is the default behavior.
exceptionMessage	string or null Only select jobs that failed due to an exception with the given message.
failedActivityId	string or null Only select jobs that failed due to an exception at an activity with the given id.
noRetriesLeft	boolean or null Only select jobs which have no retries left. Value may only be `true`, as `false` is the default behavior.
active	boolean or null Only include active jobs. Value may only be `true`, as `false` is the default behavior.
suspended	boolean or null Only include suspended jobs. Value may only be `true`, as `false` is the default behavior.
priorityLowerThanOrEquals	integer or null <int64> Only include jobs with a priority lower than or equal to the given value. Value must be a valid `long` value.
priorityHigherThanOrEquals	integer or null <int64> Only include jobs with a priority higher than or equal to the given value. Value must be a valid `long` value.
tenantIdIn	Array of strings or null Only include jobs which belong to one of the passed tenant ids.
withoutTenantId	boolean or null Only include jobs which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeJobsWithoutTenantId	boolean or null Include jobs which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Does not have an effect for the `count` endpoint.

Responses

Request samples

Payload

Content type

application/json

{"dueDates": [{"operator": "gt",
"value": "2012-07-17T17:00:00.000+0200"
},
{"operator": "lt",
"value": "2012-07-17T18:00:00.000+0200"
}
],
"createTimes": [{"operator": "gt",
"value": "2012-05-05T10:00:00.000+0200"
},
{"operator": "lt",
"value": "2012-07-16T15:00:00.000+0200"
}
]
}

Response samples

200
400

Content type

application/json

POST /job/count

{"count": 2
}

Set Job Retries Async (POST)

Create a batch to set retries of jobs asynchronously.

Authorizations:

basicAuth

Request Body schema: application/json

jobIds	Array of strings or null A list of job ids to set retries for.
	object (JobQueryDto) A Job instance query which defines a list of Job instances
dueDate	string or null <date-time> The due date to set for the job. A due date indicates when this job is ready for execution. Jobs with due dates in the past will be scheduled for execution.
retries	integer or null <int32> The number of retries to set for the resource. Must be >= 0. If this is 0, an incident is created and the task, or job, cannot be fetched, or acquired anymore unless the retries are increased again. Can not be null.

Responses

Request samples

Payload

Content type

application/json

{"retries": 5,
"dueDate": "2017-04-06T13:57:45.000+0200",
"jobIds": ["aJob",
"secondJob"
],
"jobQuery": {"dueDates": [{"operator": "gt",
"value": "2012-07-17T17:00:00.000+0200"
},
{"operator": "lt",
"value": "2012-07-17T18:00:00.000+0200"
}
]
}
}

Response samples

200
400

Content type

application/json

POST /job/retries

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"jobsCreated": 10,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"suspened": false,
"tenantId": "aTenantId",
"createUserId": "userId"
}

Activate/Suspend Jobs

Activates or suspends jobs matching the given criterion. This can only be on of:

jobDefinitionId
processDefinitionId
processInstanceId
processDefinitionKey

Authorizations:

basicAuth

Request Body schema: application/json

jobDefinitionId	string or null The job definition id of the jobs to activate or suspend.
processDefinitionId	string or null The process definition id of the jobs to activate or suspend.
processInstanceId	string or null The process instance id of the jobs to activate or suspend.
processDefinitionKey	string or null The process definition key of the jobs to activate or suspend.
processDefinitionTenantId	string or null Only activate or suspend jobs of a process definition which belongs to a tenant with the given id. Works only when selecting with `processDefinitionKey`.
processDefinitionWithoutTenantId	boolean or null Only activate or suspend jobs of a process definition which belongs to no tenant. Value may only be `true`, as `false` is the default behavior. Works only when selecting with `processDefinitionKey`.
suspended	boolean or null A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, job definition, or batch). When the value is set to true, the given instance will be suspended and when the value is set to false, the given instance will be activated.

Responses

Request samples

Payload

Content type

application/json

Example

Activates or suspends jobs with the given job definition id. PUT `/job/suspended`

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

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete Job

Deletes a job by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job to be deleted.

Responses

Response samples

404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Job

Retrieves a job by id, according to the Job interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /job/aJobId

{"id": "aJobId",
"jobDefinitionId": "f9eec330-e3ff-11e8-8f7d-e4a7a094a9d6",
"dueDate": "2018-07-17T17:00:00+0200",
"processInstanceId": "aProcessInstanceId",
"processDefinitionId": "timer:1:f9ee9c1f-e3ff-11e8-8f7d-e4a7a094a9d6",
"processDefinitionKey": "timer",
"executionId": "anExecutionId",
"retries": 0,
"exceptionMessage": "An exception Message",
"failedActivityId": "anActivityId",
"suspended": false,
"priority": 10,
"tenantId": null,
"createTime": "2018-05-05T17:00:00+0200",
"batchId": "aBatchId"
}

Set Job Due Date

Updates the due date of a job by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job to be updated.

Request Body schema: application/json

duedate	string or null <date-time> The date to set when the job has the next execution.
cascade	boolean or null A boolean value to indicate if modifications to the due date should cascade to subsequent jobs. (e.g. Modify the due date of a timer by +15 minutes. This flag indicates if a +15 minutes should be applied to all subsequent timers.) This flag only affects timer jobs and only works if due date is not null. Default: `false`

Responses

Request samples

Payload

Content type

application/json

{"duedate": "2013-08-13T18:43:28.000+0200",
"cascade": false
}

Response samples

404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Recalculate Job Due Date

Recalculates the due date of a job by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job to be updated.

query Parameters

creationDateBased

boolean

Recalculate the due date based on the creation date of the job or the current date. Value may only be false, as true is the default behavior.

Responses

Response samples

404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Execute Job

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job to be executed.

Responses

Response samples

404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Job Priority

Sets the execution priority of a job by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job to be updated.

Request Body schema: application/json

priority

integer or null <int64>

The priority of the resource.

Responses

Request samples

Payload

Content type

application/json

{"priority": 10
}

Response samples

404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Job Retries

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job to be updated.

Request Body schema: application/json

dueDate	string or null <date-time> The due date to set for the job. A due date indicates when this job is ready for execution. Jobs with due dates in the past will be scheduled for execution.
retries	integer or null <int32> The number of retries to set for the resource. Must be >= 0. If this is 0, an incident is created and the task, or job, cannot be fetched, or acquired anymore unless the retries are increased again. Can not be null.

Responses

Request samples

Payload

Content type

application/json

{"retries": 3,
"dueDate": "2017-04-06T13:57:45.000+0200"
}

Response samples

404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Exception Stacktrace

Retrieves the exception stacktrace corresponding to the passed job id.

Authorizations:

basicAuth

path Parameters

id

required

string

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

Responses

Response samples

200
404

Content type

text/plain

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

Activate/Suspend Job By Id

Activates or suspends a given job by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job to activate or suspend.

Request Body schema: application/json

suspended

boolean or null

A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, job definition, or batch). When the value is set to true, the given instance will be suspended and when the value is set to false, the given instance will be activated.

Responses

Request samples

Payload

Content type

application/json

{"suspended": true
}

Job Definition

Get Job Definitions

Queries for job definitions that fulfill given parameters. The size of the result set can be retrieved by using the Get Job Definition Count method.

Authorizations:

basicAuth

query Parameters

jobDefinitionId	string Filter by job definition id.
activityIdIn	string Only include job definitions which belong to one of the passed and comma-separated activity ids.
processDefinitionId	string Only include job definitions which exist for the given process definition id.
processDefinitionKey	string Only include job definitions which exist for the given process definition key.
jobType	string Only include job definitions which exist for the given job type. See the User Guide for more information about job types.
jobConfiguration	string Only include job definitions which exist for the given job configuration. For example: for timer jobs it is the timer configuration.
active	boolean Only include active job definitions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Only include suspended job definitions. Value may only be `true`, as `false` is the default behavior.
withOverridingJobPriority	boolean Only include job definitions that have an overriding job priority defined. The only effective value is `true`. If set to `false`, this filter is not applied.
tenantIdIn	string Only include job definitions which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean Only include job definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeJobDefinitionsWithoutTenantId	boolean Include job definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
sortBy	string Enum: "jobDefinitionId" "activityId" "processDefinitionId" "processDefinitionKey" "jobType" "jobConfiguration" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

GET /job-definition?activityIdIn=ServiceTask1,ServiceTask2

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

Get Job Definitions (POST)

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

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

jobDefinitionId	string or null Filter by job definition id.
activityIdIn	Array of strings or null Only include job definitions which belong to one of the passed activity ids.
processDefinitionId	string or null Only include job definitions which exist for the given process definition id.
processDefinitionKey	string or null Only include job definitions which exist for the given process definition key.
jobType	string or null Only include job definitions which exist for the given job type. See the User Guide for more information about job types.
jobConfiguration	string or null Only include job definitions which exist for the given job configuration. For example: for timer jobs it is the timer configuration.
active	boolean or null Only include active job definitions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean or null Only include suspended job definitions. Value may only be `true`, as `false` is the default behavior.
withOverridingJobPriority	boolean or null Only include job definitions that have an overriding job priority defined. The only effective value is `true`. If set to `false`, this filter is not applied.
tenantIdIn	Array of strings or null Only include job definitions which belong to one of the passed tenant ids.
withoutTenantId	boolean or null Only include job definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeJobDefinitionsWithoutTenantId	boolean or null Include job definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints.

Responses

Request samples

Payload

Content type

application/json

{"activityIdIn": ["ServiceTask1",
"ServiceTask2"
],
"sorting": [{"sortBy": "activityId",
"sortOrder": "asc"
},
{"sortBy": "jobType",
"sortOrder": "asc"
}
]
}

Response samples

200
400

Content type

application/json

POST /job-definition

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

Get Job Definition Count

Queries for the number of job definitions that fulfill given parameters. Takes the same parameters as the Get Job Definitions method.

Authorizations:

basicAuth

query Parameters

jobDefinitionId	string Filter by job definition id.
activityIdIn	string Only include job definitions which belong to one of the passed and comma-separated activity ids.
processDefinitionId	string Only include job definitions which exist for the given process definition id.
processDefinitionKey	string Only include job definitions which exist for the given process definition key.
jobType	string Only include job definitions which exist for the given job type. See the User Guide for more information about job types.
jobConfiguration	string Only include job definitions which exist for the given job configuration. For example: for timer jobs it is the timer configuration.
active	boolean Only include active job definitions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Only include suspended job definitions. Value may only be `true`, as `false` is the default behavior.
withOverridingJobPriority	boolean Only include job definitions that have an overriding job priority defined. The only effective value is `true`. If set to `false`, this filter is not applied.
tenantIdIn	string Only include job definitions which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean Only include job definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeJobDefinitionsWithoutTenantId	boolean Include job definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

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

{"count": 2
}

Get Job Definition Count (POST)

Queries for the number of job definitions that fulfill given parameters. This method takes the same message body as the Get Job Definitions (POST) method and therefore it is slightly more powerful than the Get Job Definition Count method.

Authorizations:

basicAuth

Request Body schema: application/json

jobDefinitionId	string or null Filter by job definition id.
activityIdIn	Array of strings or null Only include job definitions which belong to one of the passed activity ids.
processDefinitionId	string or null Only include job definitions which exist for the given process definition id.
processDefinitionKey	string or null Only include job definitions which exist for the given process definition key.
jobType	string or null Only include job definitions which exist for the given job type. See the User Guide for more information about job types.
jobConfiguration	string or null Only include job definitions which exist for the given job configuration. For example: for timer jobs it is the timer configuration.
active	boolean or null Only include active job definitions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean or null Only include suspended job definitions. Value may only be `true`, as `false` is the default behavior.
withOverridingJobPriority	boolean or null Only include job definitions that have an overriding job priority defined. The only effective value is `true`. If set to `false`, this filter is not applied.
tenantIdIn	Array of strings or null Only include job definitions which belong to one of the passed tenant ids.
withoutTenantId	boolean or null Only include job definitions which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
includeJobDefinitionsWithoutTenantId	boolean or null Include job definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints.

Responses

Request samples

Payload

Content type

application/json

{"activityIdIn": ["ServiceTask1",
"ServiceTask2"
]
}

Response samples

200
400

Content type

application/json

POST /job-definition/count

{"count": 2
}

Activate/Suspend Job Definitions

Activates or suspends job definitions with the given process definition id or process definition key.

Authorizations:

basicAuth

Request Body schema: application/json

processDefinitionId	string or null The process definition id of the job definitions to activate or suspend.
processDefinitionKey	string or null The process definition key of the job definitions to activate or suspend.
processDefinitionTenantId	string or null Only activate or suspend job definitions of a process definition which belongs to a tenant with the given id. Note that this parameter will only be considered in combination with `processDefinitionKey`.
processDefinitionWithoutTenantId	boolean or null Only activate or suspend job definitions of a process definition which belongs to no tenant. Value may only be `true`, as `false` is the default behavior. Note that this parameter will only be considered in combination with `processDefinitionKey`.
includeJobs	boolean or null A `Boolean` value which indicates whether to activate or suspend also all jobs of the referenced job definitions. When the value is set to `true`, all jobs of the provided job definitions will be activated or suspended and when the value is set to `false`, the suspension state of all jobs of the provided job definitions will not be updated.
executionDate	string or null The date on which the referenced job definitions will be activated or suspended. If null, the suspension state of the given job definitions is updated immediately. By default, the date must have the format `yyyy-MM- dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
suspended	boolean or null A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, job definition, or batch). When the value is set to true, the given instance will be suspended and when the value is set to false, the given instance will be activated.

Responses

Request samples

Payload

Content type

application/json

Example

suspend by process definition id

PUT /job-definition/suspended

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

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Job Definition

Retrieves a job definition by id, according to the JobDefinition interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job definition to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /job-definition/aJobDefinitionId

{"id": "aJobDefId",
"processDefinitionId": "aProcDefId",
"processDefinitionKey": "aProcDefKey",
"activityId": "ServiceTask1",
"jobType": "asynchronous-continuation",
"jobConfiguration": "",
"suspended": false,
"overridingJobPriority": 15,
"tenantId": null,
"deploymentId": "aDeploymentId"
}

Set Job Definition Priority by Id

Sets an overriding execution priority for jobs with the given definition id. Optionally, the priorities of all the definitions' existing jobs are updated accordingly. The priority can be reset by setting it to null, meaning that a new job's priority will not be determined based on its definition's priority any longer. See the user guide on job prioritization for details.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job definition to be updated.

Request Body schema: application/json

priority	integer or null <int64> The new execution priority number for jobs of the given definition. The definition's priority can be reset by using the value `null`. In that case, the job definition's priority no longer applies but a new job's priority is determined as specified in the process model.
includeJobs	boolean or null A boolean value indicating whether existing jobs of the given definition should receive the priority as well. Default value is `false`. Can only be `true` when the priority parameter is not `null`.

Responses

Request samples

Payload

Content type

application/json

{"priority": 10,
"includeJobs": true
}

Response samples

404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Job Retries By Job Definition Id

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job definition to be updated.

Request Body schema: application/json

retries

integer or null <int32>

The number of retries to set for the resource. Must be >= 0. If this is 0, an incident is created and the task, or job, cannot be fetched, or acquired anymore unless the retries are increased again. Can not be null.

Responses

Request samples

Payload

Content type

application/json

{"retries": 3,
"dueDate": "2017-04-06T13:57:45.000+0200"
}

Response samples

500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Activate/Suspend Job Definition By Id

Activates or suspends a given job definition by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the job definition to activate or suspend.

Request Body schema: application/json

includeJobs	boolean or null A `Boolean` value which indicates whether to activate or suspend also all jobs of the referenced job definitions. When the value is set to `true`, all jobs of the provided job definitions will be activated or suspended and when the value is set to `false`, the suspension state of all jobs of the provided job definitions will not be updated.
executionDate	string or null The date on which the referenced job definitions will be activated or suspended. If null, the suspension state of the given job definitions is updated immediately. By default, the date must have the format `yyyy-MM- dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.
suspended	boolean or null A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, job definition, or batch). When the value is set to true, the given instance will be suspended and when the value is set to false, the given instance will be activated.

Responses

Request samples

Payload

Content type

application/json

{"suspended": true,
"includeJobs": true,
"executionDate": "2013-11-21T10:49:45.000+0200"
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Message

Correlate

Correlates a message to the process engine to either trigger a message start event or an intermediate message catching event. Internally this maps to the engine's message correlation builder methods MessageCorrelationBuilder#correlateWithResult() and MessageCorrelationBuilder#correlateAllWithResult(). For more information about the correlation behavior, see the Message Events section of the BPMN 2.0 Implementation Reference.

Authorizations:

basicAuth

Request Body schema: application/json

messageName	string or null The name of the message to deliver.
businessKey	string or null 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.
tenantId	string or null Used to correlate the message for a tenant with the given id. Will only correlate to executions and process definitions which belong to the tenant. Must not be supplied in conjunction with a `withoutTenantId`.
withoutTenantId	boolean or null Default: false A Boolean value that indicates whether the message should only be correlated to executions and process definitions which belong to no tenant or not. Value may only be `true`, as `false` is the default behavior. Must not be supplied in conjunction with a `tenantId`.
processInstanceId	string or null Used to correlate the message to the process instance with the given id.
	object or null Used for correlation of process instances that wait for incoming messages. Has to be a JSON object containing key-value pairs that are matched against process instance variables during correlation. Each key is a variable name and each value a JSON variable value object with the following properties.
	object or null Local variables used for correlation of executions (process instances) that wait for incoming messages. Has to be a JSON object containing key-value pairs that are matched against local variables during correlation. Each key is a variable name and each value a JSON variable value object with the following properties.
	object or null A map of variables that is injected into the triggered execution or process instance after the message has been delivered. Each key is a variable name and each value a JSON variable value object with the following properties.
	object or null A map of local variables that is injected into the execution waiting on the message. Each key is a variable name and each value a JSON variable value object with the following properties.
	object or null A map of variables that is injected into the new scope triggered by message correlation. Each key is a variable name and each value a JSON variable value object with the following properties.
all	boolean or null Default: false A Boolean value that indicates whether the message should be correlated to exactly one entity or multiple entities. If the value is set to `false`, the message will be correlated to exactly one entity (execution or process definition). If the value is set to `true`, the message will be correlated to multiple executions and a process definition that can be instantiated by this message in one go.
resultEnabled	boolean or null Default: false A Boolean value that indicates whether the result of the correlation should be returned or not. If this property is set to `true`, there will be returned a list of message correlation result objects. Depending on the all property, there will be either one ore more returned results in the list. The default value is `false`, which means no result will be returned.
variablesInResultEnabled	boolean or null Default: false A Boolean value that indicates whether the result of the correlation should contain process variables or not. The parameter resultEnabled should be set to `true` in order to use this it. The default value is `false`, which means the variables will not be returned.

Responses

Request samples

Payload

Content type

application/json

Example

POST /message

Correlate without result

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

Response samples

200
400

Content type

application/json

Example

Status 200 Response.

The Response content of a status 200. The property variablesInResultEnabled in the request body was false (Default).

[{"resultType": "ProcessDefinition",
"execution": null,
"processInstance": {"links": [ ],
"id": "aProcInstId",
"definitionId": "aProcDefId",
"businessKey": "aKey",
"caseInstanceId": "aCaseInstId",
"ended": false,
"suspended": false,
"tenantId": "aTenantId"
}
}
]

Metrics

Get Metrics in Interval

Retrieves a list of metrics, aggregated for a given interval.

Authorizations:

basicAuth

query Parameters

name	string Enum: "activity-instance-start" "activity-instance-end" "decision-instances" "flow-node-instances" "job-acquisition-attempt" "job-acquired-success" "job-acquired-failure" "job-execution-rejected" "job-successful" "job-failed" "job-locked-exclusive" "executed-decision-elements" "history-cleanup-removed-process-instances" "history-cleanup-removed-case-instances" "history-cleanup-removed-decision-instances" "history-cleanup-removed-batch-operations" "history-cleanup-removed-task-metrics" "process-instances" The name of the metric.
reporter	string The name of the reporter (host), on which the metrics was logged. This will have value provided by the hostname configuration property.
startDate	string <date-time> The start date (inclusive).
endDate	string <date-time> The end date (exclusive).
firstResult	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
interval	string Default: 900 The interval for which the metrics should be aggregated. Time unit is seconds. Default: The interval is set to 15 minutes (900 seconds).
aggregateByReporter	string Aggregate metrics by reporter.

Responses

Response samples

200
400

Content type

application/json

[{"timestamp": "1970-01-01T01:45:00.000+0200",
"name": "flow-node-instances",
"reporter": "REPORTER",
"value": 23
}
]

Delete Task Worker Metrics

Deletes all task worker metrics prior to the given date or all if no date is provided.

Authorizations:

basicAuth

query Parameters

date	string <date-time> The date prior to which all task worker metrics should be deleted.

Responses

Response samples

403

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Sum

Retrieves the sum (count) for a given metric.

Authorizations:

basicAuth

path Parameters

metrics-name

required

string

Enum: "activity-instance-start" "activity-instance-end" "decision-instances" "flow-node-instances" "job-acquisition-attempt" "job-acquired-success" "job-acquired-failure" "job-execution-rejected" "job-successful" "job-failed" "job-locked-exclusive" "executed-decision-elements" "history-cleanup-removed-process-instances" "history-cleanup-removed-case-instances" "history-cleanup-removed-decision-instances" "history-cleanup-removed-batch-operations" "history-cleanup-removed-task-metrics" "unique-task-workers" "process-instances" "task-users"

The name of the metric.

query Parameters

startDate	string <date-time> The start date (inclusive).
endDate	string <date-time> The end date (exclusive).

Responses

Response samples

200

Content type

application/json

{"result": 4342343241
}

Migration

Execute Migration Plan

Executes a migration plan synchronously for multiple process instances. To execute a migration plan asynchronously, use the Execute Migration Plan Async(Batch) method.

For more information about the difference between synchronous and asynchronous execution of a migration plan, please refer to the related section of the user guide.

Authorizations:

basicAuth

Request Body schema: application/json

	object (MigrationPlanDto)
processInstanceIds	Array of strings or null A list of process instance ids to migrate.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
skipCustomListeners	boolean or null A boolean value to control whether execution listeners should be invoked during migration.
skipIoMappings	boolean or null A boolean value to control whether input/output mappings should be executed during migration.

Responses

Request samples

Payload

Content type

application/json

{"migrationPlan": {"sourceProcessDefinitionId": "aProcessDefinitionId1",
"targetProcessDefinitionId": "aProcessDefinitionId2",
"instructions": [{"sourceActivityIds": ["aUserTask"
],
"targetActivityIds": ["aUserTask"
]
},
{"sourceActivityIds": ["anEvent"
],
"targetActivityIds": ["anotherEvent"
],
"updateEventTrigger": true
}
],
"variables": {"foo": {"type": "Object",
"value": "[5,9]",
"valueInfo": {"objectTypeName": "java.util.ArrayList",
"serializationDataFormat": "application/json"
}
}
}
},
"processInstanceIds": ["aProcessInstance",
"anotherProcessInstance"
],
"processInstanceQuery": {"processDefinitionId": "aProcessDefinitionId1"
},
"skipCustomListeners": true
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Execute Migration Plan Async (Batch)

Executes a migration plan asynchronously (batch) for multiple process instances. To execute a migration plan synchronously, use the Execute MigrationPlan method.

For more information about the difference between synchronous and asynchronous execution of a migration plan, please refer to the related section of the user guide.

Authorizations:

basicAuth

Request Body schema: application/json

	object (MigrationPlanDto)
processInstanceIds	Array of strings or null A list of process instance ids to migrate.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
skipCustomListeners	boolean or null A boolean value to control whether execution listeners should be invoked during migration.
skipIoMappings	boolean or null A boolean value to control whether input/output mappings should be executed during migration.

Responses

Request samples

Payload

Content type

application/json

{"migrationPlan": {"sourceProcessDefinitionId": "aProcessDefinitionId1",
"targetProcessDefinitionId": "aProcessDefinitionId2",
"instructions": [{"sourceActivityIds": ["aUserTask"
],
"targetActivityIds": ["aUserTask"
]
},
{"sourceActivityIds": ["anEvent"
],
"targetActivityIds": ["anotherEvent"
],
"updateEventTrigger": true
}
],
"variables": {"foo": {"type": "Object",
"value": "[5,9]",
"valueInfo": {"objectTypeName": "java.util.ArrayList",
"serializationDataFormat": "application/json"
}
}
}
},
"processInstanceIds": ["aProcessInstance",
"anotherProcessInstance"
],
"processInstanceQuery": {"processDefinitionId": "aProcessDefinitionId1"
},
"skipCustomListeners": true
}

Response samples

200
400

Content type

application/json

POST /migration/executeAsync

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId"
}

Generate Migration Plan

Generates a migration plan for two process definitions. The generated migration plan contains migration instructions which map equal activities between the two process definitions.

Authorizations:

basicAuth

Request Body schema: application/json

sourceProcessDefinitionId	string or null The id of the source process definition for the migration.
targetProcessDefinitionId	string or null The id of the target process definition for the migration.
updateEventTriggers	boolean or null A boolean flag indicating whether instructions between events should be configured to update the event triggers.
	object or null A map of variables which will be set into the process instances' scope. Each key is a variable name and each value a JSON variable value object.

Responses

Request samples

Payload

Content type

application/json

{"sourceProcessDefinitionId": "aProcessDefinitionId1",
"targetProcessDefinitionId": "aProcessDefinitionId2",
"updateEventTriggers": true,
"variables": {"foo": {"type": "Object",
"value": "[5,6]",
"valueInfo": {"objectTypeName": "java.util.ArrayList",
"serializationDataFormat": "application/json"
}
}
}
}

Response samples

200
400

Content type

application/json

POST /migration/generate

{"sourceProcessDefinitionId": "aProcessDefinitionId1",
"targetProcessDefinitionId": "aProcessDefinitionId2",
"instructions": [{"sourceActivityIds": ["aUserTask"
],
"targetActivityIds": ["aUserTask"
],
"updateEventTrigger": false
},
{"sourceActivityIds": ["anEvent"
],
"targetActivityIds": ["anotherEvent"
],
"updateEventTrigger": true
}
],
"variables": {"foo": {"type": "Object",
"value": "[5,6]",
"valueInfo": {"objectTypeName": "java.util.ArrayList",
"serializationDataFormat": "application/json"
}
}
}
}

Validate Migration Plan

Validates a migration plan statically without executing it. This corresponds to the creation time validation described in the user guide.

Authorizations:

basicAuth

Request Body schema: application/json

sourceProcessDefinitionId	string or null The id of the source process definition for the migration.
targetProcessDefinitionId	string or null The id of the target process definition for the migration.
	Array of objects or null (MigrationInstructionDto) A list of migration instructions which map equal activities. Each migration instruction is a JSON object with the following properties:
	object or null A map of variables which will be set into the process instances' scope. Each key is a variable name and each value a JSON variable value object.

Responses

Request samples

Payload

Content type

application/json

{"sourceProcessDefinitionId": "aProcessDefinitionId1",
"targetProcessDefinitionId": "aProcessDefinitionId2",
"instructions": [{"sourceActivityIds": ["aUserTask"
],
"targetActivityIds": ["aUserTask"
]
},
{"sourceActivityIds": ["anEvent"
],
"targetActivityIds": ["anotherEvent"
],
"updateEventTrigger": true
}
],
"variables": {"foo": {"type": "Object",
"value": "...",
"valueInfo": {"objectTypeName": "java.util.ArrayList",
"serializationDataFormat": "application/x-java-serialized-object"
}
}
}
}

Response samples

200
400

Content type

application/json

POST /migration/validate

{"instructionReports": [{"instruction": {"sourceActivityIds": ["aUserTask"
],
"targetActivityIds": ["aUserTask"
],
"updateEventTrigger": false
},
"failures": ["failure1",
"failure2"
]
},
{"instruction": {"sourceActivityIds": ["anEvent"
],
"targetActivityIds": ["anotherEvent"
],
"updateEventTrigger": true
},
"failures": ["failure1",
"failure2"
]
}
],
"variableReports": {"foo": {"type": "Object",
"value": "...",
"valueInfo": {"objectTypeName": "java.util.ArrayList",
"serializationDataFormat": "application/x-java-serialized-object"
},
"failures": ["Cannot set variable with name foo. Java serialization format is prohibited"
]
}
}
}

Modification

Execute Modification

Executes a modification synchronously for multiple process instances. To modify a single process instance, use the Modify Process Instance Execution State method. To execute a modification asynchronously, use the Execute Modification Async (Batch) method.

For more information about the difference between synchronous and asynchronous execution of a modification, please refer to the related section of the user guide.

Authorizations:

basicAuth

Request Body schema: application/json

processDefinitionId	string or null The id of the process definition for the modification
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request.
processInstanceIds	Array of strings or null A list of process instance ids to modify.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
	Array of objects or null (MultipleProcessInstanceModificationInstructionDto) An array of modification instructions. The instructions are executed in the order they are in.
annotation	string or null An arbitrary text annotation set by a user for auditing reasons.

Responses

Request samples

Payload

Content type

application/json

{"processDefinitionId": "aProcessDefinitionId",
"instructions": [{"type": "startAfterActivity",
"activityId": "aUserTask"
},
{"type": "cancel",
"activityId": "anotherTask",
"cancelCurrentActiveActivityInstances": true
}
],
"processInstanceIds": ["aProcessInstance",
"anotherProcessInstance"
],
"processInstanceQuery": {"processDefinitionId": "aProcessDefinitionId"
},
"skipCustomListeners": true,
"annotation": "Modified to resolve an error."
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Execute Modification Async (Batch)

Executes a modification asynchronously for multiple process instances. To execute a modification synchronously, use the Execute Modification method.

For more information about the difference between synchronous and asynchronous execution of a modification, please refer to the related section of the user guide.

Authorizations:

basicAuth

Request Body schema: application/json

processDefinitionId	string or null The id of the process definition for the modification
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request.
processInstanceIds	Array of strings or null A list of process instance ids to modify.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
	Array of objects or null (MultipleProcessInstanceModificationInstructionDto) An array of modification instructions. The instructions are executed in the order they are in.
annotation	string or null An arbitrary text annotation set by a user for auditing reasons.

Responses

Request samples

Payload

Content type

application/json

{"processDefinitionId": "aProcessDefinitionId",
"instructions": [{"type": "startAfterActivity",
"activityId": "aUserTask"
},
{"type": "cancel",
"activityId": "anotherTask",
"cancelCurrentActiveActivityInstances": true
}
],
"processInstanceIds": ["aProcessInstance",
"anotherProcessInstance"
],
"processInstanceQuery": {"processDefinitionId": "aProcessDefinitionId"
},
"skipCustomListeners": true,
"annotation": "Modified to resolve an error."
}

Response samples

200
400

Content type

application/json

POST /modification/executeAsync

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId"
}

Process Definition

Get List

Queries 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 Definition Count method.

Authorizations:

basicAuth

query Parameters

processDefinitionId	string Filter by process definition id.
processDefinitionIdIn	string Filter by a comma-separated list of process definition ids.
name	string Filter by process definition name.
nameLike	string Filter by process definition names that the parameter is a substring of.
deploymentId	string Filter by the deployment the id belongs to.
deployedAfter	string <date-time> Filter by the deploy time of the deployment the process definition belongs to. Only selects process definitions that have been deployed after (exclusive) a specific time. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.546+0200`.
deployedAt	string <date-time> Filter by the deploy time of the deployment the process definition belongs to. Only selects process definitions that have been deployed at a specific time (exact match). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.546+0200`.
key	string Filter by process definition key, i.e., the id in the BPMN 2.0 XML. Exact match.
keysIn	string Filter by a comma-separated list of process definition keys.
keyLike	string Filter by process definition keys that the parameter is a substring of.
category	string Filter by process definition category. Exact match.
categoryLike	string Filter by process definition categories that the parameter is a substring of.
version	integer <int32> Filter by process definition version.
latestVersion	boolean Only include those process definitions that are latest versions. Value may only be `true`, as `false` is the default behavior.
resourceName	string Filter by the name of the process definition resource. Exact match.
resourceNameLike	string Filter by names of those process definition resources that the parameter is a substring of.
startableBy	string Filter by a user name who is allowed to start the process.
active	boolean Only include active process definitions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Only include suspended process definitions. Value may only be `true`, as `false` is the default behavior.
incidentId	string Filter by the incident id.
incidentType	string Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string Filter by the incident message. Exact match.
incidentMessageLike	string Filter by the incident message that the parameter is a substring of.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A process definition must have one of the given tenant ids.
withoutTenantId	boolean Only include process definitions which belong to no tenant. Value may only be true, as false is the default behavior.
includeProcessDefinitionsWithoutTenantId	boolean Include process definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
versionTag	string Filter by the version tag.
versionTagLike	string Filter by the version tag that the parameter is a substring of.
withoutVersionTag	boolean Only include process definitions without a `versionTag`.
startableInTasklist	boolean Filter by process definitions which are startable in Tasklist..
notStartableInTasklist	boolean Filter by process definitions which are not startable in Tasklist.
startablePermissionCheck	boolean Filter by process definitions which the user is allowed to start in Tasklist. If the user doesn't have these permissions the result will be empty list. The permissions are: `CREATE` permission for all Process instances `CREATE_INSTANCE` and `READ` permission on Process definition level
sortBy	string Enum: "category" "key" "id" "name" "version" "deploymentId" "deployTime" "tenantId " "versionTag" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

Response of GET /process-definition?keyLike=invoice&sortBy=version&sortOrder=asc

[{"id": "invoice:1:c3a63aaa-2046-11e7-8f94-34f39ab71d4e",
"key": "invoice",
"category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
"description": null,
"name": "Invoice Receipt",
"version": 1,
"resource": "invoice.v1.bpmn",
"deploymentId": "c398cd26-2046-11e7-8f94-34f39ab71d4e",
"diagram": null,
"suspended": false,
"tenantId": null,
"versionTag": null,
"historyTimeToLive": 5,
"startableInTasklist": true
},
{"id": "invoice:2:c3e1bd16-2046-11e7-8f94-34f39ab71d4e",
"key": "invoice",
"category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
"description": null,
"name": "Invoice Receipt",
"version": 2,
"resource": "invoice.v2.bpmn",
"deploymentId": "c3d82020-2046-11e7-8f94-34f39ab71d4e",
"diagram": null,
"suspended": false,
"tenantId": null,
"versionTag": null,
"historyTimeToLive": null,
"startableInTasklist": true
}
]

Get List Count

Requests the number of process definitions that fulfill the query criteria. Takes the same filtering parameters as the Get Definitions method.

Authorizations:

basicAuth

query Parameters

processDefinitionId	string Filter by process definition id.
processDefinitionIdIn	string Filter by a comma-separated list of process definition ids.
name	string Filter by process definition name.
nameLike	string Filter by process definition names that the parameter is a substring of.
deploymentId	string Filter by the deployment the id belongs to.
deployedAfter	string <date-time> Filter by the deploy time of the deployment the process definition belongs to. Only selects process definitions that have been deployed after (exclusive) a specific time. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.546+0200`.
deployedAt	string <date-time> Filter by the deploy time of the deployment the process definition belongs to. Only selects process definitions that have been deployed at a specific time (exact match). By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.546+0200`.
key	string Filter by process definition key, i.e., the id in the BPMN 2.0 XML. Exact match.
keysIn	string Filter by a comma-separated list of process definition keys.
keyLike	string Filter by process definition keys that the parameter is a substring of.
category	string Filter by process definition category. Exact match.
categoryLike	string Filter by process definition categories that the parameter is a substring of.
version	integer <int32> Filter by process definition version.
latestVersion	boolean Only include those process definitions that are latest versions. Value may only be `true`, as `false` is the default behavior.
resourceName	string Filter by the name of the process definition resource. Exact match.
resourceNameLike	string Filter by names of those process definition resources that the parameter is a substring of.
startableBy	string Filter by a user name who is allowed to start the process.
active	boolean Only include active process definitions. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Only include suspended process definitions. Value may only be `true`, as `false` is the default behavior.
incidentId	string Filter by the incident id.
incidentType	string Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string Filter by the incident message. Exact match.
incidentMessageLike	string Filter by the incident message that the parameter is a substring of.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A process definition must have one of the given tenant ids.
withoutTenantId	boolean Only include process definitions which belong to no tenant. Value may only be true, as false is the default behavior.
includeProcessDefinitionsWithoutTenantId	boolean Include process definitions which belong to no tenant. Can be used in combination with `tenantIdIn`. Value may only be `true`, as `false` is the default behavior.
versionTag	string Filter by the version tag.
versionTagLike	string Filter by the version tag that the parameter is a substring of.
withoutVersionTag	boolean Only include process definitions without a `versionTag`.
startableInTasklist	boolean Filter by process definitions which are startable in Tasklist..
notStartableInTasklist	boolean Filter by process definitions which are not startable in Tasklist.
startablePermissionCheck	boolean Filter by process definitions which the user is allowed to start in Tasklist. If the user doesn't have these permissions the result will be empty list. The permissions are: `CREATE` permission for all Process instances `CREATE_INSTANCE` and `READ` permission on Process definition level

Responses

Response samples

200
400

Content type

application/json

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

{"count": 1
}

Delete By Key

Deletes process definitions by a given key which belong to no tenant id.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the process definitions to be deleted.

query Parameters

cascade	boolean `true`, if all process instances, historic process instances and jobs for this process definition should be deleted.
skipCustomListeners	boolean Default: false `true`, if only the built-in ExecutionListeners should be notified with the end event.
skipIoMappings	boolean Default: false A boolean value to control whether input/output mappings should be executed during deletion. `true`, if input/output mappings should not be invoked.

Responses

Response samples

403
404

Content type

application/json

{"userId": "string",
"missingAuthorizations": [{"permissionName": "string",
"resourceName": "string",
"resourceId": "string"
}
],
"type": "string",
"message": "string",
"code": 0
}

Get

Retrieves the latest version of the process definition which belongs to no tenant according to the ProcessDefinition interface in the engine.

Authorizations:

basicAuth

path Parameters

key

required

string

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

Responses

Response samples

200
400

Content type

application/json

Response of GET /process-definition/key/invoice

{"id": "invoice:1:c3a63aaa-2046-11e7-8f94-34f39ab71d4e",
"key": "invoice",
"category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
"description": null,
"name": "Invoice Receipt",
"version": 1,
"resource": "invoice.v1.bpmn",
"deploymentId": "c398cd26-2046-11e7-8f94-34f39ab71d4e",
"diagram": null,
"suspended": false,
"tenantId": null,
"versionTag": null,
"historyTimeToLive": 5,
"startableInTasklist": true
}

Get Deployed Start Form

Retrieves the deployed form that can be referenced from a start event. For further information please refer to User Guide.

Authorizations:

basicAuth

path Parameters

key

required

string

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

Responses

Response samples

200
400
403
404

Content type

application/xhtml+xml

Resonse for GET /process-definition/key/processDefinitionKey/deployed-start-form

<form role="form" name="invoiceForm"
                                      class="form-horizontal">

                                  <div class="form-group">
                                    <label class="control-label col-md-4"
                                           for="creditor">Creditor</label>
                                    <div class="col-md-8">
                                      <input cam-variable-name="creditor"
                                             cam-variable-type="String"
                                             id="creditor"
                                             class="form-control"
                                             type="text"
                                             required />
                                      <div class="help">
                                        (e.g. &quot;Great Pizza for Everyone Inc.&quot;)
                                      </div>
                                    </div>
                                  </div>

                                </form>

Get Diagram

Retrieves the diagram for the latest version of the process definition which belongs to no tenant.

If the process definition's deployment contains an image resource with the same file name as the process definition, the deployed image will be returned by the Get Diagram endpoint. Example: someProcess.bpmn and someProcess.png. Supported file extentions for the image are: svg, png, jpg, and gif.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the process definition.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Start Form Variables

Retrieves the start form variables for the latest process definition which belongs to no tenant (only if they are defined via the Generated Task Form approach). The start form variables take form data specified on the start event into account. If form fields are defined, the variable types and default values of the form fields are taken into account.

Authorizations:

basicAuth

path Parameters

key

required

string

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

query Parameters

variableNames

string

A comma-separated list of variable names. Allows restricting the list of requested variables to the variable names in the list. It is best practice to restrict the list of variables to the variables actually required by the form in order to minimize fetching of data. If the query parameter is ommitted all variables are fetched. If the query parameter contains non-existent variable names, the variable names are ignored.

deserializeValues

boolean

Default: true

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

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

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

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

Responses

Response samples

200
404

Content type

application/json

GET /process-definition/anId/form-variables

{"amount": {"type": "integer",
"value": 5,
"valueInfo": { }
},
"firstName": {"type": "String",
"value": "Jonny",
"valueInfo": { }
}
}

Update History Time to Live

Updates history time to live for the latest version of the process definition which belongs to no tenant. The field is used within History cleanup. The value of the update is mandatory by default and does not allow null values. To enable them, please set the feature flag enforceHistoryTimeToLive to false. Read more in [Configuration Properties] (https://docs.camunda.org/manual/7.22/reference/deployment-descriptors/tags/process-engine#configuration-properties)

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the process definition to change history time to live.

Request Body schema: application/json

historyTimeToLive

integer or null <int32> >= 0

New value for historyTimeToLive field of the definition. Can be null if enforceHistoryTimeToLive is configured to false. Cannot be negative.

Responses

Request samples

Payload

Content type

application/json

{"historyTimeToLive": 5
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Rendered Start Form

Retrieves the rendered form for the latest version of the process definition which belongs to no tenant. This method can be used to get the HTML rendering of a Generated Task Form.

Authorizations:

basicAuth

path Parameters

key

required

string

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

Responses

Response samples

200
400
404

Content type

application/xhtml+xml

A /process-definition/key/anKey/rendered-form HTML GET response body providing the rendered (generated) form content.

<form class="form-horizontal">
                                  <div class="control-group">
                                    <label class="control-label">Customer ID</label>
                                    <div class="controls">
                                      <input form-field type="string" name="customerId"></input>
                                    </div>
                                  </div>
                                  <div class="control-group">
                                    <label class="control-label">Amount</label>
                                    <div class="controls">
                                      <input form-field type="number" name="amount"></input>
                                    </div>
                                  </div>
                                </form>

Start Instance

Instantiates a given process definition, starts the latest version of the process definition which belongs to no tenant. Process variables and business key may be supplied in the request body.

Authorizations:

basicAuth

path Parameters

key

required

string

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

Request Body schema: application/json

businessKey	string or null The business key of the process instance.
	object or null
caseInstanceId	string or null The case instance id the process instance is to be initialized with.
	Array of objects or null (ProcessInstanceModificationInstructionDto) Optional. A JSON array of instructions that specify which activities to start the process instance at. If this property is omitted, the process instance starts at its default blank start event.
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request. Note: This option is currently only respected when start instructions are submitted via the `startInstructions` property.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request. Note: This option is currently only respected when start instructions are submitted via the `startInstructions` property.
withVariablesInReturn	boolean or null Indicates if the variables, which was used by the process instance during execution, should be returned. Default value: `false`

Responses

Request samples

Payload

Content type

application/json

Example

Starting a process instance at its default initial activity

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

Response samples

200
400
500

Content type

application/json

Example

Status 200 Response 1

Response for starting a process instance at its default initial activity

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

Get Start Form Key

Retrieves the key of the start form for the latest version of the process definition which belongs to no tenant. The form key corresponds to the FormData#formKey property in the engine.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the process definition (the latest version thereof) for which the form key is to be retrieved.

Responses

Response samples

200
400
404

Content type

application/json

GET process-definition/key/aKey/startForm

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

Get Activity Instance Statistics

Retrieves runtime statistics of the latest version of the given process definition which belongs to no tenant, 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.

Authorizations:

basicAuth

path Parameters

key

required

string

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

query Parameters

failedJobs	boolean Whether to include the number of failed jobs in the result or not. Valid values are `true` or `false`.
incidents	boolean Valid values for this property are `true` or `false`. If this property has been set to `true` the result will include the corresponding number of incidents for each occurred incident type. If it is set to `false`, the incidents will not be included in the result. Cannot be used in combination with `incidentsForType`.
incidentsForType	string 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. Cannot be used in combination with `incidents`. See the User Guide for a list of incident types.

Responses

Response samples

200
400
404

Content type

application/json

Example

GET /process-definition/key/aProcessDefinitionKey/statistics?failedJobs=true

Request with Query Parameter failedJobs=true

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

Submit Start Form

Starts the latest version of the process definition which belongs to no tenant using a set of process variables and the business key. If the start event has Form Field Metadata defined, the process engine will perform backend validation for any form fields which have validators defined. See Documentation on Generated Task Forms.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the process definition to submit the form for.

Request Body schema: application/json

	object or null
businessKey	string or null The business key the process instance is to be initialized with. The business key uniquely identifies the process instance in the context of the given process definition.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400
404
500

Content type

application/json

POST /process-definition/key/aProcessDefinitionKey/submit-form

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

Activate/Suspend by Id

Activates or suspends a given process definition by latest version of process definition key which belongs to no tenant.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the process definition (the latest version thereof) to be activated/suspended.

Request Body schema: application/json

Note: Unallowed properties are processDefinitionId and processDefinitionKey.

suspended	boolean or null A `Boolean` value which indicates whether to activate or suspend all process definitions with the given key. When the value is set to `true`, all process definitions with the given key will be suspended and when the value is set to `false`, all process definitions with the given key will be activated.
processDefinitionId	string or null The id of the process definitions to activate or suspend.
processDefinitionKey	string or null The key of the process definitions to activate or suspend.
includeProcessInstances	boolean or null A `Boolean` value which indicates whether to activate or suspend also all process instances of the process definitions with the given key. When the value is set to `true`, all process instances of the process definitions with the given key will be activated or suspended and when the value is set to `false`, the suspension state of all process instances of the process definitions with the given key will not be updated.
executionDate	string or null <date-time> The date on which all process definitions with the given key will be activated or suspended. If `null`, the suspension state of all process definitions with the given key is updated immediately. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.

Responses

Request samples

Payload

Content type

application/json

{"suspended": true,
"includeProcessInstances": true,
"executionDate": "2013-11-21T10:49:45T14:42:45"
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete By Key

Deletes process definitions by a given key and which belong to a tenant id.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definitions to be deleted.
tenant-id required	string The id of the tenant the process definitions belong to.

query Parameters

cascade	boolean `true`, if all process instances, historic process instances and jobs for this process definition should be deleted.
skipCustomListeners	boolean Default: false `true`, if only the built-in ExecutionListeners should be notified with the end event.
skipIoMappings	boolean Default: false A boolean value to control whether input/output mappings should be executed during deletion. `true`, if input/output mappings should not be invoked.

Responses

Response samples

403
404

Content type

application/json

{"userId": "string",
"missingAuthorizations": [{"permissionName": "string",
"resourceName": "string",
"resourceId": "string"
}
],
"type": "string",
"message": "string",
"code": 0
}

Get

Retrieves the latest version of the process definition for tenant according to the ProcessDefinition interface in the engine.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant the process definition belongs to.

Responses

Response samples

200
400

Content type

application/json

Response of GET /process-definition/key/invoice/tenant-id/tenantOne

{"id": "invoice:1:c3a63aaa-2046-11e7-8f94-34f39ab71d4e",
"key": "invoice",
"category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
"description": null,
"name": "Invoice Receipt",
"version": 1,
"resource": "invoice.v1.bpmn",
"deploymentId": "c398cd26-2046-11e7-8f94-34f39ab71d4e",
"diagram": null,
"suspended": false,
"tenantId": "tenantOne",
"versionTag": null,
"historyTimeToLive": 5,
"startableInTasklist": true
}

Get Deployed Start Form

Retrieves the deployed form that can be referenced from a start event. For further information please refer to User Guide.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant the process definitions belong to.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/process-definition/key/{key}/tenant-id/{tenant-id}/deployed-start-form

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/process-definition/key/{key}/tenant-id/{tenant-id}/deployed-start-form

The API server with a custom url

/{url}/process-definition/key/{key}/tenant-id/{tenant-id}/deployed-start-form

Response samples

200
400
403
404

Content type

application/xhtml+xml

Resonse for GET /process-definition/key/processDefinitionKey/tenant-id/tenantId/deployed-start-form

<form role="form" name="invoiceForm"
                                      class="form-horizontal">

                                  <div class="form-group">
                                    <label class="control-label col-md-4"
                                           for="creditor">Creditor</label>
                                    <div class="col-md-8">
                                      <input cam-variable-name="creditor"
                                             cam-variable-type="String"
                                             id="creditor"
                                             class="form-control"
                                             type="text"
                                             required />
                                      <div class="help">
                                        (e.g. &quot;Great Pizza for Everyone Inc.&quot;)
                                      </div>
                                    </div>
                                  </div>

                                </form>

Get Diagram

Retrieves the diagram for the latest version of the process definition for tenant.

If the process definition's deployment contains an image resource with the same file name as the process definition, the deployed image will be returned by the Get Diagram endpoint. Example: someProcess.bpmn and someProcess.png. Supported file extentions for the image are: svg, png, jpg, and gif.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition.
tenant-id required	string The id of the tenant the process definition belongs to.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Start Form Variables

Retrieves the start form variables for the latest process definition for a tenant (only if they are defined via the Generated Task Form approach). The start form variables take form data specified on the start event into account. If form fields are defined, the variable types and default values of the form fields are taken into account.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant the process definition belongs to.

query Parameters

variableNames

string

A comma-separated list of variable names. Allows restricting the list of requested variables to the variable names in the list. It is best practice to restrict the list of variables to the variables actually required by the form in order to minimize fetching of data. If the query parameter is ommitted all variables are fetched. If the query parameter contains non-existent variable names, the variable names are ignored.

deserializeValues

boolean

Default: true

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

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

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

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

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/process-definition/key/{key}/tenant-id/{tenant-id}/form-variables

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/process-definition/key/{key}/tenant-id/{tenant-id}/form-variables

The API server with a custom url

/{url}/process-definition/key/{key}/tenant-id/{tenant-id}/form-variables

Response samples

200
404

Content type

application/json

GET /process-definition/anId/form-variables

{"amount": {"type": "integer",
"value": 5,
"valueInfo": { }
},
"firstName": {"type": "String",
"value": "Jonny",
"valueInfo": { }
}
}

Update History Time to Live

Updates history time to live for the latest version of the process definition for a tenant. The field is used within History cleanup.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition to change history time to live.
tenant-id required	string The id of the tenant the process definition belongs to.

Request Body schema: application/json

historyTimeToLive

integer or null <int32> >= 0

New value for historyTimeToLive field of the definition. Can be null if enforceHistoryTimeToLive is configured to false. Cannot be negative.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/process-definition/key/{key}/tenant-id/{tenant-id}/history-time-to-live

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/process-definition/key/{key}/tenant-id/{tenant-id}/history-time-to-live

The API server with a custom url

/{url}/process-definition/key/{key}/tenant-id/{tenant-id}/history-time-to-live

Request samples

Payload

Content type

application/json

{"historyTimeToLive": 5
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Rendered Start Form

Retrieves the rendered form for the latest version of the process definition for a tenant. This method can be used to get the HTML rendering of a Generated Task Form.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant the process definition belongs to.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/process-definition/key/{key}/tenant-id/{tenant-id}/rendered-form

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/process-definition/key/{key}/tenant-id/{tenant-id}/rendered-form

The API server with a custom url

/{url}/process-definition/key/{key}/tenant-id/{tenant-id}/rendered-form

Response samples

200
400
404

Content type

application/xhtml+xml

A /process-definition/key/anKey/tenand-id/aTenantId/rendered-form HTML GET response body providing the rendered (generated) form content.

<form class="form-horizontal">
                                  <div class="control-group">
                                    <label class="control-label">Customer ID</label>
                                    <div class="controls">
                                      <input form-field type="string" name="customerId"></input>
                                    </div>
                                  </div>
                                  <div class="control-group">
                                    <label class="control-label">Amount</label>
                                    <div class="controls">
                                      <input form-field type="number" name="amount"></input>
                                    </div>
                                  </div>
                                </form>

Start Instance

Instantiates a given process definition, starts the latest version of the process definition for tenant. Process variables and business key may be supplied in the request body.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant the process definition belongs to.

Request Body schema: application/json

businessKey	string or null The business key of the process instance.
	object or null
caseInstanceId	string or null The case instance id the process instance is to be initialized with.
	Array of objects or null (ProcessInstanceModificationInstructionDto) Optional. A JSON array of instructions that specify which activities to start the process instance at. If this property is omitted, the process instance starts at its default blank start event.
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request. Note: This option is currently only respected when start instructions are submitted via the `startInstructions` property.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request. Note: This option is currently only respected when start instructions are submitted via the `startInstructions` property.
withVariablesInReturn	boolean or null Indicates if the variables, which was used by the process instance during execution, should be returned. Default value: `false`

Responses

Request samples

Payload

Content type

application/json

Example

Starting a process instance at its default initial activity

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

Response samples

200
400
500

Content type

application/json

Example

Status 200 Response 1

Response for starting a process instance at its default initial activity

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

Get Start Form Key

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

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) for which the form key is to be retrieved.
tenant-id required	string The id of the tenant the process definition belongs to.

Responses

Response samples

200
400
404

Content type

application/json

GET process-definition/key/aKey/tenant-id/aTenantId/startForm

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

Get Activity Instance Statistics

Retrieves runtime statistics of the latest version of the given process definition for a tenant, 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.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) to be retrieved.
tenant-id required	string The id of the tenant the process definition belongs to.

query Parameters

failedJobs	boolean Whether to include the number of failed jobs in the result or not. Valid values are `true` or `false`.
incidents	boolean Valid values for this property are `true` or `false`. If this property has been set to `true` the result will include the corresponding number of incidents for each occurred incident type. If it is set to `false`, the incidents will not be included in the result. Cannot be used in combination with `incidentsForType`.
incidentsForType	string 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. Cannot be used in combination with `incidents`. See the User Guide for a list of incident types.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/process-definition/key/{key}/tenant-id/{tenant-id}/statistics

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/process-definition/key/{key}/tenant-id/{tenant-id}/statistics

The API server with a custom url

/{url}/process-definition/key/{key}/tenant-id/{tenant-id}/statistics

Response samples

200
400
404

Content type

application/json

Example

GET /process-definition/key/aProcessDefinitionKey/tenant-id/aTenantId/statistics?failedJobs=true

Request with Query Parameter failedJobs=true

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

Submit Start Form

Starts the latest version of the process definition for a tenant using a set of process variables and the business key. If the start event has Form Field Metadata defined, the process engine will perform backend validation for any form fields which have validators defined. See Documentation on Generated Task Forms.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition to submit the form for.
tenant-id required	string The id of the tenant the process definition belongs to.

Request Body schema: application/json

	object or null
businessKey	string or null The business key the process instance is to be initialized with. The business key uniquely identifies the process instance in the context of the given process definition.

Responses

The API server for the default process engine

http://{host}:{port}/{contextPath}/process-definition/key/{key}/tenant-id/{tenant-id}/submit-form

The API server for a named process engine

http://{host}:{port}/{contextPath}/engine/{engineName}/process-definition/key/{key}/tenant-id/{tenant-id}/submit-form

The API server with a custom url

/{url}/process-definition/key/{key}/tenant-id/{tenant-id}/submit-form

Request samples

Payload

Content type

application/json

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

Response samples

200
400
404
500

Content type

application/json

POST /process-definition/key/aProcessDefinitionKey/tenant-id/aTenantId/submit-form

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

Activate/Suspend by Id

Activates or suspends a given process definition by the latest version of the process definition for tenant.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) to be activated/suspended.
tenant-id required	string The id of the tenant the process definition belongs to.

Request Body schema: application/json

Note: Unallowed properties are processDefinitionId and processDefinitionKey.

suspended	boolean or null A `Boolean` value which indicates whether to activate or suspend all process definitions with the given key. When the value is set to `true`, all process definitions with the given key will be suspended and when the value is set to `false`, all process definitions with the given key will be activated.
processDefinitionId	string or null The id of the process definitions to activate or suspend.
processDefinitionKey	string or null The key of the process definitions to activate or suspend.
includeProcessInstances	boolean or null A `Boolean` value which indicates whether to activate or suspend also all process instances of the process definitions with the given key. When the value is set to `true`, all process instances of the process definitions with the given key will be activated or suspended and when the value is set to `false`, the suspension state of all process instances of the process definitions with the given key will not be updated.
executionDate	string or null <date-time> The date on which all process definitions with the given key will be activated or suspended. If `null`, the suspension state of all process definitions with the given key is updated immediately. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.

Responses

Request samples

Payload

Content type

application/json

{"suspended": true,
"includeProcessInstances": true,
"executionDate": "2013-11-21T10:49:45T14:42:45"
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get XML

Retrieves latest version the BPMN 2.0 XML of a process definition. Returns the XML for the latest version of the process definition for tenant.

Authorizations:

basicAuth

path Parameters

key required	string The key of the process definition (the latest version thereof) whose XML should be retrieved.
tenant-id required	string The id of the tenant the process definition belongs to.

Responses

Response samples

200
403
404

Content type

application/json

{"id": "anProcessDefinitionId",
"bpmn20Xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<definitions\n                         xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"\n                         xmlns:camunda=\"http://camunda.org/schema/1.0/bpmn\"\n                         targetNamespace=\"Examples\">\n                         <process id=\"oneTaskProcess\" isExecutable=\"true\">\n                           <startEvent id=\"theStart\" />\n                           <sequenceFlow id=\"flow1\" sourceRef=\"theStart\" targetRef=\"theEnd\" />\n                           <endEvent id=\"theEnd\" />\n                         </process>\n                       </definitions>"
}

Get XML

Retrieves latest version the BPMN 2.0 XML of a process definition.

Authorizations:

basicAuth

path Parameters

key

required

string

The key of the process definition (the latest version thereof) whose XML should be retrieved.

Responses

Response samples

200
403
404

Content type

application/json

{"id": "anProcessDefinitionId",
"bpmn20Xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<definitions\n                         xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"\n                         xmlns:camunda=\"http://camunda.org/schema/1.0/bpmn\"\n                         targetNamespace=\"Examples\">\n                         <process id=\"oneTaskProcess\" isExecutable=\"true\">\n                           <startEvent id=\"theStart\" />\n                           <sequenceFlow id=\"flow1\" sourceRef=\"theStart\" targetRef=\"theEnd\" />\n                           <endEvent id=\"theEnd\" />\n                         </process>\n                       </definitions>"
}

Get Process Instance Statistics

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

Authorizations:

basicAuth

query Parameters

failedJobs	boolean Whether to include the number of failed jobs in the result or not. Valid values are `true` or `false`.
incidents	boolean Valid values for this property are `true` or `false`. If this property has been set to `true` the result will include the corresponding number of incidents for each occurred incident type. If it is set to `false`, the incidents will not be included in the result. Cannot be used in combination with `incidentsForType`.
incidentsForType	string 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. Cannot be used in combination with `incidents`. See the User Guide for a list of incident types.
rootIncidents	boolean Valid values for this property are `true` or `false`. If this property has been set to `true` the result will include the corresponding number of root incidents for each occurred incident type. If it is set to `false`, the incidents will not be included in the result. Cannot be used in combination with `incidentsForType` or `incidents`.

Responses

Response samples

200
400

Content type

application/json

Example

GET /process-definition/statistics?failedJobs=true

Request with Query Parameter failedJobs=true

[{"@class": "org.camunda.bpm.engine.rest.dto.repository.ProcessDefinitionStatisticsResultDto",
"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,
"tenantId": null,
"versionTag": "1.0.0",
"historyTimeToLive": null,
"startableInTasklist": false
},
"incidents": [ ]
},
{"@class": "org.camunda.bpm.engine.rest.dto.repository.ProcessDefinitionStatisticsResultDto",
"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,
"tenantId": null,
"versionTag": null,
"historyTimeToLive": null,
"startableInTasklist": false
},
"incidents": [ ]
}
]

Activate/Suspend By Key

Activates or suspends process definitions with the given process definition key.

Authorizations:

basicAuth

Request Body schema: application/json

Note: Unallowed property is processDefinitionId.

suspended	boolean or null A `Boolean` value which indicates whether to activate or suspend all process definitions with the given key. When the value is set to `true`, all process definitions with the given key will be suspended and when the value is set to `false`, all process definitions with the given key will be activated.
processDefinitionId	string or null The id of the process definitions to activate or suspend.
processDefinitionKey	string or null The key of the process definitions to activate or suspend.
includeProcessInstances	boolean or null A `Boolean` value which indicates whether to activate or suspend also all process instances of the process definitions with the given key. When the value is set to `true`, all process instances of the process definitions with the given key will be activated or suspended and when the value is set to `false`, the suspension state of all process instances of the process definitions with the given key will not be updated.
executionDate	string or null <date-time> The date on which all process definitions with the given key will be activated or suspended. If `null`, the suspension state of all process definitions with the given key is updated immediately. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete

Deletes a running process instance by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition to be deleted.

query Parameters

cascade	boolean `true`, if all process instances, historic process instances and jobs for this process definition should be deleted.
skipCustomListeners	boolean Default: false `true`, if only the built-in ExecutionListeners should be notified with the end event.
skipIoMappings	boolean Default: false A boolean value to control whether input/output mappings should be executed during deletion. `true`, if input/output mappings should not be invoked.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition to be retrieved.

Responses

Response samples

200
400

Content type

application/json

Response of GET /process-definition/invoice:1:c3a63aaa-2046-11e7-8f94-34f39ab71d4e

{"id": "invoice:1:c3a63aaa-2046-11e7-8f94-34f39ab71d4e",
"key": "invoice",
"category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
"description": null,
"name": "Invoice Receipt",
"version": 1,
"resource": "invoice.v1.bpmn",
"deploymentId": "c398cd26-2046-11e7-8f94-34f39ab71d4e",
"diagram": null,
"suspended": false,
"tenantId": null,
"versionTag": null,
"historyTimeToLive": 5,
"startableInTasklist": true
}

Get Deployed Start Form

Retrieves the deployed form that can be referenced from a start event. For further information please refer to User Guide.

Authorizations:

basicAuth

path Parameters

id

required

string

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

Responses

Response samples

200
400
403
404

Content type

application/xhtml+xml

Resonse for GET /process-definition/processDefinitionId/deployed-start-form

<form role="form" name="invoiceForm"
                                      class="form-horizontal">

                                  <div class="form-group">
                                    <label class="control-label col-md-4"
                                           for="creditor">Creditor</label>
                                    <div class="col-md-8">
                                      <input cam-variable-name="creditor"
                                             cam-variable-type="String"
                                             id="creditor"
                                             class="form-control"
                                             type="text"
                                             required />
                                      <div class="help">
                                        (e.g. &quot;Great Pizza for Everyone Inc.&quot;)
                                      </div>
                                    </div>
                                  </div>

                                </form>

Get Diagram

Retrieves the diagram of a process definition.

If the process definition's deployment contains an image resource with the same file name as the process definition, the deployed image will be returned by the Get Diagram endpoint. Example: someProcess.bpmn and someProcess.png. Supported file extentions for the image are: svg, png, jpg, and gif.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Start Form Variables

Retrieves the start form variables for a process definition (only if they are defined via the Generated Task Form approach). The start form variables take form data specified on the start event into account. If form fields are defined, the variable types and default values of the form fields are taken into account.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition to retrieve the variables for.

query Parameters

variableNames

string

A comma-separated list of variable names. Allows restricting the list of requested variables to the variable names in the list. It is best practice to restrict the list of variables to the variables actually required by the form in order to minimize fetching of data. If the query parameter is ommitted all variables are fetched. If the query parameter contains non-existent variable names, the variable names are ignored.

deserializeValues

boolean

Default: true

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

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

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

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

Responses

Response samples

200
404

Content type

application/json

GET /process-definition/anId/form-variables

{"amount": {"type": "integer",
"value": 5,
"valueInfo": { }
},
"firstName": {"type": "String",
"value": "Jonny",
"valueInfo": { }
}
}

Update History Time to Live

Updates history time to live for process definition. The field is used within History cleanup. The value of the update is mandatory by default and does not allow null values. To enable them, please set the feature flag enforceHistoryTimeToLive to false. Read more in [Configuration Properties] (https://docs.camunda.org/manual/7.22/reference/deployment-descriptors/tags/process-engine#configuration-properties)

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition to change history time to live.

Request Body schema: application/json

historyTimeToLive

integer or null <int32> >= 0

New value for historyTimeToLive field of the definition. Can be null if enforceHistoryTimeToLive is configured to false. Cannot be negative.

Responses

Request samples

Payload

Content type

application/json

{"historyTimeToLive": 5
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Rendered Start Form

Retrieves the rendered form for a process definition. This method can be used to get the HTML rendering of a Generated Task Form.

Authorizations:

basicAuth

path Parameters

id

required

string

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

Responses

Response samples

200
400
404

Content type

application/xhtml+xml

A /process-definition/anId/rendered-form HTML GET response body providing the rendered (generated) form content.

<form class="form-horizontal">
                                  <div class="control-group">
                                    <label class="control-label">Customer ID</label>
                                    <div class="controls">
                                      <input form-field type="string" name="customerId"></input>
                                    </div>
                                  </div>
                                  <div class="control-group">
                                    <label class="control-label">Amount</label>
                                    <div class="controls">
                                      <input form-field type="number" name="amount"></input>
                                    </div>
                                  </div>
                                </form>

Restart Process Instance

Restarts process instances that were canceled or terminated synchronously. Can also restart completed process instances. It will create a new instance using the original instance information. To execute the restart asynchronously, use the Restart Process Instance Async method.

For more information about the difference between synchronous and asynchronous execution, please refer to the related section of the User Guide.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition of the process instances to restart.

Request Body schema: application/json

processInstanceIds	Array of strings or null A list of process instance ids to restart.
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started as part of this request.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started as part of this request.
initialVariables	boolean or null Set the initial set of variables during restart. By default, the last set of variables is used.
withoutBusinessKey	boolean or null Do not take over the business key of the historic process instance.
	Array of objects or null (RestartProcessInstanceModificationInstructionDto) Optional. A JSON array of instructions that specify which activities to start the process instance at. If this property is omitted, the process instance starts at its default blank start event.

Responses

Request samples

Payload

Content type

application/json

Example

Restarting one or more Process Instances with known processInstanceIds

{"instructions": [{"type": "startAfterActivity",
"activityId": "aUserTask"
}
],
"processInstanceIds": ["aProcessInstance",
"anotherProcessInstance"
],
"initialVariables": true,
"skipCustomListeners": true,
"withoutBusinessKey": true
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Restart Process Instance Async

Restarts process instances that were canceled or terminated asynchronously. Can also restart completed process instances. It will create a new instance using the original instance information. To execute the restart asynchronously, use the Restart Process Instance method.

For more information about the difference between synchronous and asynchronous execution, please refer to the related section of the User Guide.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition of the process instances to restart.

Request Body schema: application/json

processInstanceIds	Array of strings or null A list of process instance ids to restart.
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started as part of this request.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started as part of this request.
initialVariables	boolean or null Set the initial set of variables during restart. By default, the last set of variables is used.
withoutBusinessKey	boolean or null Do not take over the business key of the historic process instance.
	Array of objects or null (RestartProcessInstanceModificationInstructionDto) Optional. A JSON array of instructions that specify which activities to start the process instance at. If this property is omitted, the process instance starts at its default blank start event.

Responses

Request samples

Payload

Content type

application/json

Example

Restarting one or more Process Instances with known processInstanceIds

{"instructions": [{"type": "startAfterActivity",
"activityId": "aUserTask"
}
],
"processInstanceIds": ["aProcessInstance",
"anotherProcessInstance"
],
"initialVariables": true,
"skipCustomListeners": true,
"withoutBusinessKey": true
}

Response samples

200
400
404

Content type

application/json

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"jobsCreated": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"suspended": false,
"createUserId": "demo"
}

Start Instance

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition to be retrieved.

Request Body schema: application/json

businessKey	string or null The business key of the process instance.
	object or null
caseInstanceId	string or null The case instance id the process instance is to be initialized with.
	Array of objects or null (ProcessInstanceModificationInstructionDto) Optional. A JSON array of instructions that specify which activities to start the process instance at. If this property is omitted, the process instance starts at its default blank start event.
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request. Note: This option is currently only respected when start instructions are submitted via the `startInstructions` property.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request. Note: This option is currently only respected when start instructions are submitted via the `startInstructions` property.
withVariablesInReturn	boolean or null Indicates if the variables, which was used by the process instance during execution, should be returned. Default value: `false`

Responses

Request samples

Payload

Content type

application/json

Example

Starting a process instance at its default initial activity

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

Response samples

200
400
500

Content type

application/json

Example

Status 200 Response 1

Response for starting a process instance at its default initial activity

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

Get Start Form Key

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

Authorizations:

basicAuth

path Parameters

id

required

string

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

Responses

Response samples

200
400
404

Content type

application/json

GET process-definition/anId/startForm

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

Get Static Called Process Definitions

For the given process, returns a list of called process definitions corresponding to the CalledProcessDefinition interface in the engine. The list contains all process definitions that are referenced statically by call activities in the given process. This endpoint does not resolve process definitions that are referenced with expressions. Each called process definition contains a list of call activity ids, which specifies the call activities that are calling that process. This endpoint does not resolve references to case definitions.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition.

Responses

Response samples

200
404

Content type

application/json

GET /process-definition/aProcessDefinitionId/static-called-process-definitions

[{"id": "ACalledProcess:1:1bbd4e83-f8f1-11eb-9344",
"key": "ACalledProcess",
"category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
"description": null,
"name": "ACalledProcess",
"version": 1,
"resource": "called-process.bpmn",
"deploymentId": "1baa3baf-f8f1-11eb-9344-0e0bbdd53e42",
"diagram": null,
"suspended": false,
"tenantId": null,
"versionTag": null,
"historyTimeToLive": null,
"calledFromActivityIds": ["aCallActivityId"
],
"callingProcessDefinitionId": "aProcessDefinitionId",
"startableInTasklist": true
},
{"id": "AnotherCalledProcess:2:1bc2f3d5-f8f1-11eb-9344",
"key": "AnotherCalledProcess",
"category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
"description": null,
"name": "AnotherCalledProcess",
"version": 2,
"resource": "another-called-process.bpmn",
"deploymentId": "1baa3baf-f8f1-11eb-9344-0e0bbdd53e42",
"diagram": null,
"suspended": false,
"tenantId": null,
"versionTag": null,
"historyTimeToLive": null,
"calledFromActivityIds": ["aSecondCallActivityId",
"aThirdCallActivityId"
],
"callingProcessDefinitionId": "aProcessDefinitionId",
"startableInTasklist": true
}
]

Get Activity Instance Statistics

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition.

query Parameters

failedJobs	boolean Whether to include the number of failed jobs in the result or not. Valid values are `true` or `false`.
incidents	boolean Valid values for this property are `true` or `false`. If this property has been set to `true` the result will include the corresponding number of incidents for each occurred incident type. If it is set to `false`, the incidents will not be included in the result. Cannot be used in combination with `incidentsForType`.
incidentsForType	string 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. Cannot be used in combination with `incidents`. See the User Guide for a list of incident types.

Responses

Response samples

200
400
404

Content type

application/json

Example

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

Request with Query Parameter failedJobs=true

[{"@class": "org.camunda.bpm.engine.rest.dto.repository.ActivityStatisticsResultDto",
"id": "anActivity",
"instances": 123,
"failedJobs": 42,
"incidents": [ ]
},
{"@class": "org.camunda.bpm.engine.rest.dto.repository.ActivityStatisticsResultDto",
"id": "anotherActivity",
"instances": 124,
"failedJobs": 43,
"incidents": [ ]
}
]

Submit Start Form

Starts a process instance using a set of process variables and the business key. If the start event has Form Field Metadata defined, the process engine will perform backend validation for any form fields which have validators defined. See Documentation on Generated Task Forms.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition to submit the form for.

Request Body schema: application/json

	object or null
businessKey	string or null The business key the process instance is to be initialized with. The business key uniquely identifies the process instance in the context of the given process definition.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400
404
500

Content type

application/json

POST /process-definition/aProcessDefinitionId/submit-form

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

Activate/Suspend By Id

Activates or suspends a given process definition by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition to activate or suspend.

Request Body schema: application/json

Note: Unallowed properties are processDefinitionId and processDefinitionKey.

suspended	boolean or null A `Boolean` value which indicates whether to activate or suspend all process definitions with the given key. When the value is set to `true`, all process definitions with the given key will be suspended and when the value is set to `false`, all process definitions with the given key will be activated.
processDefinitionId	string or null The id of the process definitions to activate or suspend.
processDefinitionKey	string or null The key of the process definitions to activate or suspend.
includeProcessInstances	boolean or null A `Boolean` value which indicates whether to activate or suspend also all process instances of the process definitions with the given key. When the value is set to `true`, all process instances of the process definitions with the given key will be activated or suspended and when the value is set to `false`, the suspension state of all process instances of the process definitions with the given key will not be updated.
executionDate	string or null <date-time> The date on which all process definitions with the given key will be activated or suspended. If `null`, the suspension state of all process definitions with the given key is updated immediately. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.000+0200`.

Responses

Request samples

Payload

Content type

application/json

{"suspended": true,
"includeProcessInstances": true,
"executionDate": "2013-11-21T10:49:45T14:42:45"
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get XML

Retrieves the BPMN 2.0 XML of a process definition.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process definition.

Responses

Response samples

200
400
403
404

Content type

application/json

{"id": "anProcessDefinitionId",
"bpmn20Xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<definitions\n                         xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"\n                         xmlns:camunda=\"http://camunda.org/schema/1.0/bpmn\"\n                         targetNamespace=\"Examples\">\n                         <process id=\"oneTaskProcess\" isExecutable=\"true\">\n                           <startEvent id=\"theStart\" />\n                           <sequenceFlow id=\"flow1\" sourceRef=\"theStart\" targetRef=\"theEnd\" />\n                           <endEvent id=\"theEnd\" />\n                         </process>\n                       </definitions>"
}

Process Instance

Get List

Queries 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 Instance Count method.

Authorizations:

basicAuth

query Parameters

sortBy	string Enum: "instanceId" "definitionKey" "definitionId" "tenantId" "businessKey" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
processInstanceIds	string Filter by a comma-separated list of process instance ids.
businessKey	string Filter by process instance business key.
businessKeyLike	string Filter by process instance business key that the parameter is a substring of.
caseInstanceId	string Filter by case instance id.
processDefinitionId	string Filter by the deployment the id belongs to.
processDefinitionKey	string Filter by the key of the process definition the instances run on.
processDefinitionKeyIn	string Filter by a comma-separated list of process definition keys. A process instance must have one of the given process definition keys.
processDefinitionKeyNotIn	string Exclude instances by a comma-separated list of process definition keys. A process instance must not have one of the given process definition keys.
deploymentId	string Filter by the deployment the id belongs to.
superProcessInstance	string Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstance	string Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id.
superCaseInstance	string Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
subCaseInstance	string Restrict query to all process instances that have the given case instance as a sub case instance. Takes a case instance id.
active	boolean Default: false Only include active process instances. Value may only be true, as false is the default behavior.
suspended	boolean Default: false Only include suspended process instances. Value may only be true, as false is the default behavior.
withIncident	boolean Default: false Filter by presence of incidents. Selects only process instances that have an incident.
incidentId	string Filter by the incident id.
incidentType	string Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string Filter by the incident message. Exact match.
incidentMessageLike	string Filter by the incident message that the parameter is a substring of.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A process instance must have one of the given tenant ids.
withoutTenantId	boolean Default: false Only include process instances which belong to no tenant.
processDefinitionWithoutTenantId	boolean Default: false Only include process instances which process definition has no tenant id.
activityIdIn	string Filter by a comma-separated list of activity ids. A process instance must currently wait in a leaf activity with one of the given activity ids.
rootProcessInstances	boolean Default: false Restrict the query to all process instances that are top level process instances.
leafProcessInstances	boolean Default: false Restrict the query to all process instances that are leaf instances. (i.e. don't have any sub instances).
variables	string Only include process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Default: false Match all variable names in this query case-insensitively. If set to true variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Default: false Match all variable values in this query case-insensitively. If set to true variableValue and variablevalue are treated as equal.

Responses

Response samples

200
400

Content type

application/json

Response for GET /process-instance?variables=myVariable_eq_camunda,mySecondVariable_neq_aBadValue

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

Get List (POST)

Queries for process instances that fulfill given parameters through a JSON object. This method is slightly more powerful than the Get Instances method because it allows filtering by multiple process variables of types string, number or boolean.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

deploymentId	string or null Filter by the deployment the id belongs to.
processDefinitionId	string or null Filter by the process definition the instances run on.
processDefinitionKey	string or null Filter by the key of the process definition the instances run on.
processDefinitionKeyIn	Array of strings or null Filter by a list of process definition keys. A process instance must have one of the given process definition keys. Must be a JSON array of Strings.
processDefinitionKeyNotIn	Array of strings or null Exclude instances by a list of process definition keys. A process instance must not have one of the given process definition keys. Must be a JSON array of Strings.
businessKey	string or null Filter by process instance business key.
businessKeyLike	string or null Filter by process instance business key that the parameter is a substring of.
caseInstanceId	string or null Filter by case instance id.
superProcessInstance	string or null Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstance	string or null Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id.
superCaseInstance	string or null Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
subCaseInstance	string or null Restrict query to all process instances that have the given case instance as a sub case instance. Takes a case instance id.
active	boolean or null Only include active process instances. Value may only be true, as false is the default behavior.
suspended	boolean or null Only include suspended process instances. Value may only be true, as false is the default behavior.
processInstanceIds	Array of strings or null Filter by a list of process instance ids. Must be a JSON array of Strings.
withIncident	boolean or null Filter by presence of incidents. Selects only process instances that have an incident.
incidentId	string or null Filter by the incident id.
incidentType	string or null Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string or null Filter by the incident message. Exact match.
incidentMessageLike	string or null Filter by the incident message that the parameter is a substring of.
tenantIdIn	Array of strings or null Filter by a list of tenant ids. A process instance must have one of the given tenant ids. Must be a JSON array of Strings.
withoutTenantId	boolean or null Only include process instances which belong to no tenant. Value may only be true, as false is the default behavior.
processDefinitionWithoutTenantId	boolean or null Only include process instances which process definition has no tenant id.
activityIdIn	Array of strings or null Filter by a list of activity ids. A process instance must currently wait in a leaf activity with one of the given activity ids.
rootProcessInstances	boolean or null Restrict the query to all process instances that are top level process instances.
leafProcessInstances	boolean or null Restrict the query to all process instances that are leaf instances. (i.e. don't have any sub instances)
	Array of objects or null (VariableQueryParameterDto) 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. The `value` may be String, Number or Boolean. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`.
variableNamesIgnoreCase	boolean or null Match all variable names in this query case-insensitively. If set to true variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match all variable values in this query case-insensitively. If set to true variableValue and variablevalue are treated as equal.
orQueries	Array of objects or null (ProcessInstanceQueryDto) A JSON array of nested process instance queries with OR semantics. A process instance matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a process instance must fulfill at least one predicate of each query (Conjunctive Normal Form). All process instance query properties can be used except for: `sorting` See the User guide for more information about OR queries.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400

Content type

application/json

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

Get List Count

Queries for the number of process instances that fulfill given parameters.

Authorizations:

basicAuth

query Parameters

processInstanceIds	string Filter by a comma-separated list of process instance ids.
businessKey	string Filter by process instance business key.
businessKeyLike	string Filter by process instance business key that the parameter is a substring of.
caseInstanceId	string Filter by case instance id.
processDefinitionId	string Filter by the deployment the id belongs to.
processDefinitionKey	string Filter by the key of the process definition the instances run on.
processDefinitionKeyIn	string Filter by a comma-separated list of process definition keys. A process instance must have one of the given process definition keys.
processDefinitionKeyNotIn	string Exclude instances by a comma-separated list of process definition keys. A process instance must not have one of the given process definition keys.
deploymentId	string Filter by the deployment the id belongs to.
superProcessInstance	string Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstance	string Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id.
superCaseInstance	string Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
subCaseInstance	string Restrict query to all process instances that have the given case instance as a sub case instance. Takes a case instance id.
active	boolean Default: false Only include active process instances. Value may only be true, as false is the default behavior.
suspended	boolean Default: false Only include suspended process instances. Value may only be true, as false is the default behavior.
withIncident	boolean Default: false Filter by presence of incidents. Selects only process instances that have an incident.
incidentId	string Filter by the incident id.
incidentType	string Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string Filter by the incident message. Exact match.
incidentMessageLike	string Filter by the incident message that the parameter is a substring of.
tenantIdIn	string Filter by a comma-separated list of tenant ids. A process instance must have one of the given tenant ids.
withoutTenantId	boolean Default: false Only include process instances which belong to no tenant.
processDefinitionWithoutTenantId	boolean Default: false Only include process instances which process definition has no tenant id.
activityIdIn	string Filter by a comma-separated list of activity ids. A process instance must currently wait in a leaf activity with one of the given activity ids.
rootProcessInstances	boolean Default: false Restrict the query to all process instances that are top level process instances.
leafProcessInstances	boolean Default: false Restrict the query to all process instances that are leaf instances. (i.e. don't have any sub instances).
variables	string Only include process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Default: false Match all variable names in this query case-insensitively. If set to true variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Default: false Match all variable values in this query case-insensitively. If set to true variableValue and variablevalue are treated as equal.

Responses

Response samples

200
400

Content type

application/json

Response for GET /process-instance/count?variables=myVariable_eq_camunda

{"count": 1
}

Get List Count (POST)

Queries for the number of process instances that fulfill the given parameters. This method takes the same message body as the Get Instances (POST) method and therefore it is slightly more powerful than the Get Instance Count method.

Authorizations:

basicAuth

Request Body schema: application/json

deploymentId	string or null Filter by the deployment the id belongs to.
processDefinitionId	string or null Filter by the process definition the instances run on.
processDefinitionKey	string or null Filter by the key of the process definition the instances run on.
processDefinitionKeyIn	Array of strings or null Filter by a list of process definition keys. A process instance must have one of the given process definition keys. Must be a JSON array of Strings.
processDefinitionKeyNotIn	Array of strings or null Exclude instances by a list of process definition keys. A process instance must not have one of the given process definition keys. Must be a JSON array of Strings.
businessKey	string or null Filter by process instance business key.
businessKeyLike	string or null Filter by process instance business key that the parameter is a substring of.
caseInstanceId	string or null Filter by case instance id.
superProcessInstance	string or null Restrict query to all process instances that are sub process instances of the given process instance. Takes a process instance id.
subProcessInstance	string or null Restrict query to all process instances that have the given process instance as a sub process instance. Takes a process instance id.
superCaseInstance	string or null Restrict query to all process instances that are sub process instances of the given case instance. Takes a case instance id.
subCaseInstance	string or null Restrict query to all process instances that have the given case instance as a sub case instance. Takes a case instance id.
active	boolean or null Only include active process instances. Value may only be true, as false is the default behavior.
suspended	boolean or null Only include suspended process instances. Value may only be true, as false is the default behavior.
processInstanceIds	Array of strings or null Filter by a list of process instance ids. Must be a JSON array of Strings.
withIncident	boolean or null Filter by presence of incidents. Selects only process instances that have an incident.
incidentId	string or null Filter by the incident id.
incidentType	string or null Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage	string or null Filter by the incident message. Exact match.
incidentMessageLike	string or null Filter by the incident message that the parameter is a substring of.
tenantIdIn	Array of strings or null Filter by a list of tenant ids. A process instance must have one of the given tenant ids. Must be a JSON array of Strings.
withoutTenantId	boolean or null Only include process instances which belong to no tenant. Value may only be true, as false is the default behavior.
processDefinitionWithoutTenantId	boolean or null Only include process instances which process definition has no tenant id.
activityIdIn	Array of strings or null Filter by a list of activity ids. A process instance must currently wait in a leaf activity with one of the given activity ids.
rootProcessInstances	boolean or null Restrict the query to all process instances that are top level process instances.
leafProcessInstances	boolean or null Restrict the query to all process instances that are leaf instances. (i.e. don't have any sub instances)
	Array of objects or null (VariableQueryParameterDto) 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. The `value` may be String, Number or Boolean. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`.
variableNamesIgnoreCase	boolean or null Match all variable names in this query case-insensitively. If set to true variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match all variable values in this query case-insensitively. If set to true variableValue and variablevalue are treated as equal.
orQueries	Array of objects or null (ProcessInstanceQueryDto) A JSON array of nested process instance queries with OR semantics. A process instance matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a process instance must fulfill at least one predicate of each query (Conjunctive Normal Form). All process instance query properties can be used except for: `sorting` See the User guide for more information about OR queries.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400

Content type

application/json

{"count": 1
}

Delete Async (POST)

Deletes multiple process instances asynchronously (batch).

Authorizations:

basicAuth

Request Body schema: application/json

Unallowed property: historicProcessInstanceQuery

processInstanceIds	Array of strings or null A list process instance ids to delete.
deleteReason	string or null A string with delete reason.
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request.
skipSubprocesses	boolean or null Skip deletion of the subprocesses related to deleted processes as part of this request.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances

Responses

Request samples

Payload

Content type

application/json

{"deleteReason": "aReason",
"processInstanceIds": ["aProcess",
"secondProcess"
],
"skipCustomListeners": true,
"skipSubprocesses": true,
"skipIoMappings": false
}

Response samples

200
400

Content type

application/json

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"jobsCreated": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"suspended": false,
"createUserId": "demo"
}

Delete Async Historic Query Based (POST)

Deletes a set of process instances asynchronously (batch) based on a historic process instance query.

Authorizations:

basicAuth

Request Body schema: application/json

Unallowed property: processInstanceQuery

processInstanceIds	Array of strings or null A list process instance ids to delete.
deleteReason	string or null A string with delete reason.
skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request.
skipSubprocesses	boolean or null Skip deletion of the subprocesses related to deleted processes as part of this request.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances

Responses

Request samples

Payload

Content type

application/json

{"deleteReason": "aReason",
"historicProcessInstanceQuery": {"startedBefore": "2017-04-28T11:24:37.765+0200"
},
"skipCustomListeners": true,
"skipSubprocesses": true,
"skipIoMappings": false
}

Response samples

200
400

Content type

application/json

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"jobsCreated": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"suspended": false,
"createUserId": "demo"
}

Set Job Retries Async (POST)

Create a batch to set retries of jobs associated with given processes asynchronously.

Authorizations:

basicAuth

Request Body schema: application/json

Please note that if both processInstances and processInstanceQuery are provided, then the resulting execution will be performed on the union of these sets. Unallowed property: historicProcessInstanceQuery

processInstances	Array of strings or null A list of process instance ids to fetch jobs, for which retries will be set.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
jobIds	Array of strings or null A list of job ids to set retries for.
	object (JobQueryDto) A Job instance query which defines a list of Job instances
dueDate	string or null <date-time> The due date to set for the job. A due date indicates when this job is ready for execution. Jobs with due dates in the past will be scheduled for execution.
retries	integer or null <int32> The number of retries to set for the resource. Must be >= 0. If this is 0, an incident is created and the task, or job, cannot be fetched, or acquired anymore unless the retries are increased again. Can not be null.

Responses

Request samples

Payload

Content type

application/json

{"retries": 5,
"dueDate": "2017-04-06T13:57:45.000+0200",
"processInstances": ["aProcess",
"secondProcess"
],
"processInstanceQuery": {"processDefinitionId": "aProcessDefinitionId"
}
}

Response samples

200
400

Content type

application/json

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"batchJobsPerSeed": 100,
"jobsCreated": 10,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"suspended": false,
"tenantId": "aTenantId",
"createUserId": "demo"
}

Set Job Retries Async Historic Query Based (POST)

Create a batch to set retries of jobs asynchronously based on a historic process instance query.

Authorizations:

basicAuth

Request Body schema: application/json

Please note that if both processInstances and historicProcessInstanceQuery are provided, then the resulting execution will be performed on the union of these sets. Unallowed property: processInstanceQuery

processInstances	Array of strings or null A list of process instance ids to fetch jobs, for which retries will be set.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
jobIds	Array of strings or null A list of job ids to set retries for.
	object (JobQueryDto) A Job instance query which defines a list of Job instances
dueDate	string or null <date-time> The due date to set for the job. A due date indicates when this job is ready for execution. Jobs with due dates in the past will be scheduled for execution.
retries	integer or null <int32> The number of retries to set for the resource. Must be >= 0. If this is 0, an incident is created and the task, or job, cannot be fetched, or acquired anymore unless the retries are increased again. Can not be null.

Responses

Request samples

Payload

Content type

application/json

{"retries": 5,
"dueDate": "2017-04-06T13:57:45.000+0200",
"historicProcessInstanceQuery": {"startedBefore": "2017-04-28T11:24:37.769+0200"
},
"processInstances": ["aProcess",
"secondProcess"
]
}

Response samples

200
400

Content type

application/json

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"jobsCreated": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"suspended": false,
"createUserId": "demo"
}

Correlate Message Async (POST)

Correlates a message asynchronously to executions that are waiting for this message. Messages will not be correlated to process definition-level start message events to start process instances.

Authorizations:

basicAuth

Request Body schema: application/json

messageName	string or null The name of the message to correlate. Corresponds to the 'name' element of the message defined in BPMN 2.0 XML. Can be null to correlate by other criteria only.
processInstanceIds	Array of strings or null A list of process instance ids that define a group of process instances to which the operation will correlate a message. Please note that if `processInstanceIds`, `processInstanceQuery` and `historicProcessInstanceQuery` are defined, the resulting operation will be performed on the union of these sets.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
	object or null All variables the operation will set in the root scope of the process instances the message is correlated to.

Responses

Request samples

Payload

Content type

application/json

Correlate a message to process instances in a batch

{"messageName": "a-message-name",
"processInstanceIds": ["b4d2ad98-7240-11e9-98b7-be5e0f7575b7"
],
"processInstanceQuery": {"processDefinitionKey": "my-process-definition-key"
},
"variables": {"myVariableName": {"value": "myStringValue"
}
}
}

Response samples

200
400
403

Content type

application/json

{"id": "120b568d-724a-11e9-98b7-be5e0f7575b7",
"type": "correlate-message",
"totalJobs": 12,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "120b5690-724a-11e9-98b7-be5e0f7575b7",
"monitorJobDefinitionId": "120b568f-724a-11e9-98b7-be5e0f7575b7",
"batchJobDefinitionId": "120b568e-724a-11e9-98b7-be5e0f7575b7",
"tenantId": "accounting",
"suspended": false,
"createUserId": null
}

Activate/Suspend In Group

Activates or suspends process instances by providing certain criteria:

Activate/Suspend Process Instance By Process Definition Id

suspend
processDefinitionId

Activate/Suspend Process Instance By Process Definition Key

suspend
processDefinitionKey
processDefinitionTenantId
processDefinitionWithoutTenantId

Activate/Suspend Process Instance In Group

suspend
processInstanceIds
processInstanceQuery
historicProcessInstanceQuery

Authorizations:

basicAuth

Request Body schema: application/json

processDefinitionId	string or null The process definition id of the process instances to activate or suspend. Note: This parameter can be used only with combination of `suspended`.
processDefinitionKey	string or null The process definition key of the process instances to activate or suspend. Note: This parameter can be used only with combination of `suspended`, `processDefinitionTenantId`, and `processDefinitionWithoutTenantId`.
processDefinitionTenantId	string or null Only activate or suspend process instances of a process definition which belongs to a tenant with the given id. Note: This parameter can be used only with combination of `suspended`, `processDefinitionKey`, and `processDefinitionWithoutTenantId`.
processDefinitionWithoutTenantId	boolean or null Only activate or suspend process instances of a process definition which belongs to no tenant. Value may only be true, as false is the default behavior. Note: This parameter can be used only with combination of `suspended`, `processDefinitionKey`, and `processDefinitionTenantId`.
processInstanceIds	Array of strings or null A list of process instance ids which defines a group of process instances which will be activated or suspended by the operation. Note: This parameter can be used only with combination of `suspended`, `processInstanceQuery`, and `historicProcessInstanceQuery`.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
suspended	boolean or null A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, job definition, or batch). When the value is set to true, the given instance will be suspended and when the value is set to false, the given instance will be activated.

Responses

Request samples

Payload

Content type

application/json

Example

PUT `/process-instance/suspended`

Suspend Process Instance By Process Definition Id

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

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Activate/Suspend In Batch

Activates or suspends process instances asynchronously with a list of process instance ids, a process instance query, and/or a historical process instance query.

Authorizations:

basicAuth

Request Body schema: application/json

processInstanceIds	Array of strings or null A list of process instance ids which defines a group of process instances which will be activated or suspended by the operation.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
suspended	boolean or null A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, job definition, or batch). When the value is set to true, the given instance will be suspended and when the value is set to false, the given instance will be activated.

Responses

Request samples

Payload

Content type

application/json

Suspend Process Instance In Batch

{"processInstanceIds": ["processInstanceId1",
"processInstanceIdN"
],
"suspended": true
}

Response samples

200
400

Content type

application/json

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"jobsCreated": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"suspended": false,
"createUserId": "demo"
}

Set Variables Async (POST)

Update or create runtime process variables in the root scope of process instances.

Authorizations:

basicAuth

Request Body schema: application/json

processInstanceIds	Array of strings or null A list of process instance ids that define a group of process instances to which the operation will set variables. Please note that if `processInstanceIds`, `processInstanceQuery` and `historicProcessInstanceQuery` are defined, the resulting operation will be performed on the union of these sets.
	object (ProcessInstanceQueryDto) A process instance query which defines a group of process instances
	object (HistoricProcessInstanceQueryDto) A historic process instance query which defines a group of historic process instances
	object or null A variables the operation will set in the root scope of the process instances.

Responses

Request samples

Payload

Content type

application/json

Set variables to process instances in a batch

{"processInstanceIds": ["b4d2ad98-7240-11e9-98b7-be5e0f7575b7"
],
"processInstanceQuery": {"processDefinitionKey": "my-process-definition-key"
},
"variables": {"myVariableName": {"value": "myStringValue"
}
}
}

Response samples

200
400
403

Content type

application/json

{"id": "120b568d-724a-11e9-98b7-be5e0f7575b7",
"type": "set-variables",
"totalJobs": 12,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "120b5690-724a-11e9-98b7-be5e0f7575b7",
"monitorJobDefinitionId": "120b568f-724a-11e9-98b7-be5e0f7575b7",
"batchJobDefinitionId": "120b568e-724a-11e9-98b7-be5e0f7575b7",
"tenantId": "accounting",
"suspended": false,
"createUserId": null
}

Delete

Deletes a running process instance by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance to be deleted.

query Parameters

skipCustomListeners	boolean Default: false If set to true, the custom listeners will be skipped.
skipIoMappings	boolean Default: false If set to true, the input/output mappings will be skipped.
skipSubprocesses	boolean Default: false If set to true, subprocesses related to deleted processes will be skipped.
failIfNotExists	boolean Default: true If set to false, the request will still be successful if the process id is not found.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Process Instance

Retrieves a process instance by id, according to the ProcessInstance interface in the engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance to be retrieved.

Responses

Response samples

200
404

Content type

application/json

{"id": "aProcessInstanceId",
"definitionId": "aProcDefId",
"businessKey": "aKey",
"caseInstanceId": "aCaseInstanceId",
"ended": false,
"suspended": false,
"tenantId": null
}

Get Activity Instance

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

Authorizations:

basicAuth

path Parameters

id

required

string

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

Responses

Response samples

200
500

Content type

application/json

{"id": "eca75c6b-f70c-11e9-8777-e4a7a094a9d6",
"parentActivityInstanceId": null,
"activityId": "invoice:2:e9d77375-f70c-11e9-8777-e4a7a094a9d6",
"activityType": "processDefinition",
"processInstanceId": "eca75c6b-f70c-11e9-8777-e4a7a094a9d6",
"processDefinitionId": "invoice:2:e9d77375-f70c-11e9-8777-e4a7a094a9d6",
"childActivityInstances": [{"id": "approveInvoice:eca89509-f70c-11e9-8777-e4a7a094a9d6",
"parentActivityInstanceId": "eca75c6b-f70c-11e9-8777-e4a7a094a9d6",
"activityId": "approveInvoice",
"activityType": "userTask",
"processInstanceId": "eca75c6b-f70c-11e9-8777-e4a7a094a9d6",
"processDefinitionId": "invoice:2:e9d77375-f70c-11e9-8777-e4a7a094a9d6",
"childActivityInstances": [ ],
"childTransitionInstances": [ ],
"executionIds": ["eca75c6b-f70c-11e9-8777-e4a7a094a9d6"
],
"activityName": "Approve Invoice",
"incidentIds": ["648d7e21-f71c-11e9-a725-e4a7a094a9d6"
],
"incidents": [{"id": "648d7e21-f71c-11e9-a725-e4a7a094a9d6",
"activityId": "AttachedTimerBoundaryEvent"
}
],
"name": "Approve Invoice"
}
],
"childTransitionInstances": [ ],
"executionIds": ["eca75c6b-f70c-11e9-8777-e4a7a094a9d6"
],
"activityName": "Invoice Receipt",
"incidentIds": null,
"incidents": null,
"name": "Invoice Receipt"
}

Get Process Instance Comments

Gets the comments for a process instance by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance to retrieve the comments for.

Responses

Response samples

200
404

Content type

application/json

[{"id": "commentId",
"userId": "userId",
"taskId": "aTaskId",
"processInstanceId": "aProcessInstanceId",
"time": "2013-01-02T21:37:03.764+0200",
"message": "message",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
},
{"id": "anotherCommentId",
"userId": "anotherUserId",
"taskId": "aTaskId",
"processInstanceId": "aProcessInstanceId",
"time": "2013-02-23T20:37:43.975+0200",
"message": "anotherMessage",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
},
{"id": "yetAnotherCommentId",
"userId": "yetAnotherUserId",
"taskId": "aTaskId",
"processInstanceId": "aProcessInstanceId",
"time": "2013-04-21T10:15:23.764+0200",
"message": "yetAnotherMessage",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Modify Process Instance Execution State

Submits a list of modification instructions to change a process instance's execution state. A modification instruction is one of the following:

Starting execution before an activity
Starting execution after an activity on its single outgoing sequence flow
Starting execution on a specific sequence flow
Canceling an activity instance, transition instance, or all instances (activity or transition) for an activity

Instructions are executed immediately and in the order they are provided in this request's body. Variables can be provided with every starting instruction.

The exact semantics of modification can be read about in the User guide.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance to modify.

Request Body schema: application/json

skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request.
	Array of objects or null (ProcessInstanceModificationInstructionDto) JSON array of modification instructions. The instructions are executed in the order they are in.
annotation	string or null An arbitrary text annotation set by a user for auditing reasons.

Responses

Request samples

Payload

Content type

application/json

{"skipCustomListeners": true,
"skipIoMappings": true,
"instructions": [{"type": "startBeforeActivity",
"activityId": "activityId",
"variables": {"var": {"value": "aVariableValue",
"local": false,
"type": "String"
},
"varLocal": {"value": "anotherVariableValue",
"local": true,
"type": "String"
}
}
},
{"type": "cancel",
"activityInstanceId": "anActivityInstanceId"
}
],
"annotation": "Modified to resolve an error."
}

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Modify Process Instance Execution State Async

Submits a list of modification instructions to change a process instance's execution state async. A modification instruction is one of the following:

Starting execution before an activity
Starting execution after an activity on its single outgoing sequence flow
Starting execution on a specific sequence flow
Cancelling an activity instance, transition instance, or all instances (activity or transition) for an activity

Instructions are executed asynchronous and in the order they are provided in this request's body. Variables can be provided with every starting instruction.

The exact semantics of modification can be read about in the User guide.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance to modify.

Request Body schema: application/json

skipCustomListeners	boolean or null Skip execution listener invocation for activities that are started or ended as part of this request.
skipIoMappings	boolean or null Skip execution of input/output variable mappings for activities that are started or ended as part of this request.
	Array of objects or null (ProcessInstanceModificationInstructionDto) JSON array of modification instructions. The instructions are executed in the order they are in.
annotation	string or null An arbitrary text annotation set by a user for auditing reasons.

Responses

Request samples

Payload

Content type

application/json

{"skipCustomListeners": true,
"skipIoMappings": true,
"instructions": [{"type": "startBeforeActivity",
"activityId": "activityId"
},
{"type": "cancel",
"activityInstanceId": "anActivityInstanceId"
}
],
"annotation": "Modified to resolve an error."
}

Response samples

200
400
403
500

Content type

application/json

{"id": "aBatchId",
"type": "aBatchType",
"totalJobs": 10,
"jobsCreated": 10,
"batchJobsPerSeed": 100,
"invocationsPerBatchJob": 1,
"seedJobDefinitionId": "aSeedJobDefinitionId",
"monitorJobDefinitionId": "aMonitorJobDefinitionId",
"batchJobDefinitionId": "aBatchJobDefinitionId",
"tenantId": "aTenantId",
"suspended": false,
"createUserId": "demo"
}

Activate/Suspend Process Instance By Id

Activates or suspends a given process instance by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance to activate or suspend.

Request Body schema: application/json

suspended

boolean or null

A Boolean value which indicates whether to activate or suspend a given instance (e.g. process instance, job, job definition, or batch). When the value is set to true, the given instance will be suspended and when the value is set to false, the given instance will be activated.

Responses

Request samples

Payload

Content type

application/json

{"suspended": true
}

Get Process Variables

Retrieves all variables of a given process instance by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance to retrieve the variables from.

query Parameters

deserializeValues

boolean

Default: true

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

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

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

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

Responses

Response samples

200
500

Content type

application/json

Example

GET `/process-instance/aProcessInstanceId/variables`

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

Update/Delete Process Variables

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the process instance to set variables for.

Request Body schema: application/json

	object or null A JSON object containing variable key-value pairs.
deletions	Array of strings or null An array of String keys of variables to be deleted.

Responses

Request samples

Payload

Content type

application/json

Status 204 Response: No content.

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

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete Process Variable

Deletes a variable of a process instance by id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the process instance to delete the variable from.
varName required	string The name of the variable to delete.

Responses

Get Process Variable

Retrieves a variable of a given process instance by id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the process instance to retrieve the variable for.
varName required	string The name of the variable to retrieve.

query Parameters

deserializeValue

boolean

Default: true

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

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

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

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

Responses

Response samples

200
400

Content type

application/json

Example

GET `/process-instance/aProcessInstanceId/variables/myObject123`

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

Update Process Variable

Sets a variable of a given process instance by id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the process instance to set the variable for.
varName required	string The name of the variable to set.

Request Body schema: application/json

value	any (AnyValue) Can be any value - string, number, boolean, array or object. Note: Not every endpoint supports every type.
type	string or null The value type of the variable.
	object A JSON object containing additional, value-type-dependent properties. For serialized variables of type Object, the following properties can be provided: `objectTypeName`: A string representation of the object's type name. `serializationDataFormat`: The serialization format used to store the variable. For serialized variables of type File, the following properties can be provided: `filename`: The name of the file. This is not the variable name but the name that will be used when downloading the file again. `mimetype`: The MIME type of the file that is being uploaded. `encoding`: The encoding of the file that is being uploaded. The following property can be provided for all value types: `transient`: Indicates whether the variable should be transient or not. See documentation for more informations. (Not applicable for `decision-definition`, `/process-instance/variables-async`, and `/migration/executeAsync` endpoints)

Responses

Request samples

Payload

Content type

application/json

Example

PUT /process-instance/aProcessInstanceId/variables/aVarName

Status 204. No content.

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

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Process Variable (Binary)

Retrieves the content of a Process Variable by the Process Instance id and the Process Variable name. Applicable for byte array or file Process Variables.

Authorizations:

basicAuth

path Parameters

id required	string The id of the process instance to retrieve the variable for.
varName required	string The name of the variable to retrieve.

Responses

Response samples

200
400
404

Content type

application/octet-stream

Content-Type: application/octet-stream

Update Process Variable (Binary)

Sets the serialized value for a binary variable or the binary value for a file variable.

Authorizations:

basicAuth

path Parameters

id required	string The id of the process instance to retrieve the variable for.
varName required	string The name of the variable to retrieve.

Request Body schema: multipart/form-data

For binary variables a multipart form submit with the following parts:

data	string or null <binary> The binary data to be set. For File variables, this multipart can contain the filename, binary value and MIME type of the file variable to be set Only the filename is mandatory.
valueType	string or null Enum: "Bytes" "File" The name of the variable type. Either Bytes for a byte array variable or File for a file variable.

Responses

Request samples

Payload

Content type

multipart/form-data

Example

POST `/process-instance/aProcessInstanceId/variables/aVarName/data` (1)

Post binary content of a byte array variable.


                        ```
                        ------------------------------354ddb6baeff
                        Content-Disposition: form-data; name="data"; filename="image.png"
                        Content-Type: application/octet-stream
                        Content-Transfer-Encoding: binary

                        <<Byte Stream ommitted>>
                        ------------------------------354ddb6baeff
                        Content-Disposition: form-data; name="valueType"
                        Content-Type: text/plain; charset=US-ASCII
                        Content-Transfer-Encoding: 8bit

                        Bytes
                        ------------------------------1e838f8f632a--
                        ```

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Signal

Event

A signal is an event of global scope (broadcast semantics) and is delivered to all active handlers. Internally this maps to the engine's signal event received builder method RuntimeService#createSignalEvent(). For more information about the signal behavior, see the Signal Events section of the BPMN 2.0 Implementation Reference.

Authorizations:

basicAuth

Request Body schema: application/json

name	string The name of the signal to deliver. Note: This property is mandatory.
executionId	string or null Optionally specifies a single execution which is notified by the signal. Note: If no execution id is defined the signal is broadcasted to all subscribed handlers.
	object or null A JSON object containing variable key-value pairs. Each key is a variable name and each value a JSON variable value object.
tenantId	string or null Specifies a tenant to deliver the signal. The signal can only be received on executions or process definitions which belongs to the given tenant. Note: Cannot be used in combination with executionId.
withoutTenantId	boolean or null If true the signal can only be received on executions or process definitions which belongs to no tenant. Value may not be false as this is the default behavior. Note: Cannot be used in combination with `executionId`.

Responses

Request samples

Payload

Content type

application/json

The content of the Request Body

{"name": "policy_conditions_changed",
"variables": {"newTimePeriodInMonth": {"value": 24
}
}
}

Response samples

400
403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Schema Log

Get List

Queries for schema log entries that fulfill given parameters.

Authorizations:

basicAuth

query Parameters

version	string Only return schema log entries with a specific version.
sortBy	string Value: "timestamp" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200

Content type

application/json

The Response content of a status 200

[{"id": "0",
"version": "7.11.0",
"timestamp": "2019-05-13T09:07:11.751+0200"
},
{"id": "1",
"version": "7.11.1",
"timestamp": "2019-06-1T17:22:05.123+0200"
}
]

Get List (POST)

Queries for schema log entries that fulfill given parameters.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

version	string or null The version of the schema.
	Array of objects or null A JSON array of criteria to sort the result by. Each element of the array is a JSON object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc.

Responses

Request samples

Payload

Content type

application/json

The content of the Request Body

{"version": "7.11.0",
"sortBy": "timestamp",
"sortOrder": "asc"
}

Response samples

200

Content type

application/json

The Response content of a status 200

[{"id": "0",
"version": "7.11.0",
"timestamp": "2019-05-13T09:07:11.751+0200"
}
]

Task

Get List

Queries for tasks that fulfill a given filter. The size of the result set can be retrieved by using the Get Task Count method.

Security Consideration: There are several query parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.

Authorizations:

basicAuth

query Parameters

taskId	string Restrict to task with the given id.
taskIdIn	string Restrict to tasks with any of the given ids.
processInstanceId	string Restrict to tasks that belong to process instances with the given id.
processInstanceIdIn	string Restrict to tasks that belong to process instances with the given ids.
processInstanceBusinessKey	string Restrict to tasks that belong to process instances with the given business key.
processInstanceBusinessKeyExpression	string Restrict to tasks that belong to process instances with the given business key which is described by an expression. See the user guide for more information on available functions.
processInstanceBusinessKeyIn	string Restrict to tasks that belong to process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike	string Restrict to tasks that have a process instance business key that has the parameter value as a substring.
processInstanceBusinessKeyLikeExpression	string Restrict to tasks that have a process instance business key that has the parameter value as a substring and is described by an expression. See the user guide for more information on available functions.
processDefinitionId	string Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey	string Restrict to tasks that belong to a process definition with the given key.
processDefinitionKeyIn	string Restrict to tasks that belong to a process definition with one of the given keys. The keys need to be in a comma-separated list.
processDefinitionName	string Restrict to tasks that belong to a process definition with the given name.
processDefinitionNameLike	string Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId	string Restrict to tasks that belong to an execution with the given id.
caseInstanceId	string Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey	string Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike	string Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId	string Restrict to tasks that belong to a case definition with the given id.
caseDefinitionKey	string Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName	string Restrict to tasks that belong to a case definition with the given name.
caseDefinitionNameLike	string Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId	string Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn	string Only include tasks which belong to one of the passed and comma-separated activity instance ids.
tenantIdIn	string Only include tasks which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean Default: false Only include tasks which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
assignee	string Restrict to tasks that the given user is assigned to.
assigneeExpression	string Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike	string Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression	string Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
assigneeIn	string Only include tasks which are assigned to one of the passed and comma-separated user ids.
assigneeNotIn	string Only include tasks which are not assigned to one of the passed and comma-separated user ids.
owner	string Restrict to tasks that the given user owns.
ownerExpression	string Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup	string Only include tasks that are offered to the given group.
candidateGroupLike	string Only include tasks that are offered to groups that have the parameter value as a substring.
candidateGroupExpression	string Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
candidateUser	string Only include tasks that are offered to the given user or to one of his groups.
candidateUserExpression	string Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
includeAssignedTasks	boolean Default: false Also include tasks that are assigned to users in candidate queries. Default is to only include tasks that are not assigned to any user if you query by candidate user or group(s).
involvedUser	string Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee).
involvedUserExpression	string Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
assigned	boolean Default: false If set to `true`, restricts the query to all tasks that are assigned.
unassigned	boolean Default: false If set to `true`, restricts the query to all tasks that are unassigned.
taskDefinitionKey	string Restrict to tasks that have the given key.
taskDefinitionKeyIn	string Restrict to tasks that have one of the given keys. The keys need to be in a comma-separated list.
taskDefinitionKeyLike	string Restrict to tasks that have a key that has the parameter value as a substring.
name	string Restrict to tasks that have the given name.
nameNotEqual	string Restrict to tasks that do not have the given name.
nameLike	string Restrict to tasks that have a name with the given parameter value as substring.
nameNotLike	string Restrict to tasks that do not have a name with the given parameter value as substring.
description	string Restrict to tasks that have the given description.
descriptionLike	string Restrict to tasks that have a description that has the parameter value as a substring.
priority	integer Restrict to tasks that have the given priority.
maxPriority	integer Restrict to tasks that have a lower or equal priority.
minPriority	integer Restrict to tasks that have a higher or equal priority.
dueDate	string Restrict to tasks that are due on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.546+0200`.
dueDateExpression	string Restrict to tasks that are due on the date described by the given expression. See the User Guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
dueAfter	string Restrict to tasks that are due after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.435+0200`.
dueAfterExpression	string Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
dueBefore	string Restrict to tasks that are due before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.243+0200`.
dueBeforeExpression	string Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
withoutDueDate	boolean Default: false Only include tasks which have no due date. Value may only be `true`, as `false` is the default behavior.
followUpDate	string Restrict to tasks that have a followUp date on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.342+0200`.
followUpDateExpression	string Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpAfter	string Restrict to tasks that have a followUp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.542+0200`.
followUpAfterExpression	string Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpBefore	string Restrict to tasks that have a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.234+0200`.
followUpBeforeExpression	string Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpBeforeOrNotExistent	string Restrict to tasks that have no followUp date or a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.432+0200`. The typical use case is to query all `active` tasks for a user for a given date.
followUpBeforeOrNotExistentExpression	string Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdOn	string Restrict to tasks that were created on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.324+0200`.
createdOnExpression	string Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdAfter	string Restrict to tasks that were created after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.342+0200`.
createdAfterExpression	string Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdBefore	string Restrict to tasks that were created before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.332+0200`.
createdBeforeExpression	string Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
updatedAfter	string Restrict to tasks that were updated after the given date. Every action that fires a task update event is considered as updating the task. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.332+0200`.
updatedAfterExpression	string Restrict to tasks that were updated after the date described by the given expression. Every action that fires a task update event is considered as updating the task. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
delegationState	string Enum: "PENDING" "RESOLVED" Restrict to tasks that are in the given delegation state. Valid values are `PENDING` and `RESOLVED`.
candidateGroups	string Restrict to tasks that are offered to any of the given candidate groups. Takes a comma-separated list of group names, so for example `developers,support,sales`.
candidateGroupsExpression	string Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to `java.util.List` of Strings.
withCandidateGroups	boolean Default: false Only include tasks which have a candidate group. Value may only be `true`, as `false` is the default behavior.
withoutCandidateGroups	boolean Default: false Only include tasks which have no candidate group. Value may only be `true`, as `false` is the default behavior.
withCandidateUsers	boolean Default: false Only include tasks which have a candidate user. Value may only be `true`, as `false` is the default behavior.
withoutCandidateUsers	boolean Default: false Only include tasks which have no candidate users. Value may only be `true`, as `false` is the default behavior.
active	boolean Default: false Only include active tasks. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Default: false Only include suspended tasks. Value may only be `true`, as `false` is the default behavior.
taskVariables	string Only include tasks that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
processVariables	string Only include tasks that belong to process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`; `notLike`. `key` and `value` may not contain underscore or comma characters.
caseInstanceVariables	string Only include tasks that belong to case instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Default: false Match all variable names in this query case-insensitively. If set `variableName` and `variablename` are treated as equal.
variableValuesIgnoreCase	boolean Default: false Match all variable values in this query case-insensitively. If set `variableValue` and `variablevalue` are treated as equal.
parentTaskId	string Restrict query to all tasks that are sub tasks of the given task. Takes a task id.
withCommentAttachmentInfo	boolean Default: false Check if task has attachments and/or comments. Value may only be `true`, as `false` is the default behavior. Adding the filter will do additional attachment and comments queries to the database, it might slow down the query in case of tables having high volume of data. This param is not considered for count queries
sortBy	string Enum: "instanceId" "caseInstanceId" "dueDate" "executionId" "caseExecutionId" "assignee" "created" "lastUpdated" "description" "id" "name" "nameCaseInsensitive" "priority" "processVariable" "executionVariable" "taskVariable" "caseExecutionVariable" "caseInstanceVariable" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

Example

Status 200 response 1

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

[{"id": "anId",
"name": "aName",
"assignee": "anAssignee",
"created": "2013-01-23T13:42:42.657+0200",
"due": "2013-01-23T13:49:42.323+0200",
"followUp:": "2013-01-23T13:44:42.987+0200",
"lastUpdated:": "2013-01-23T13:44:42.987+0200",
"delegationState": "RESOLVED",
"description": "aDescription",
"executionId": "anExecution",
"owner": "anOwner",
"parentTaskId": "aParentId",
"priority": 42,
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"caseDefinitionId": "aCaseDefId",
"caseInstanceId": "aCaseInstId",
"caseExecutionId": "aCaseExecution",
"taskDefinitionKey": "aTaskDefinitionKey",
"suspended": false,
"formKey": "aFormKey",
"camundaFormRef": {"key": "aCamundaFormKey",
"binding": "version",
"version": 2
},
"tenantId": "aTenantId",
"taskState": "aTaskState"
}
]

Get List (POST)

Queries for tasks that fulfill a given filter. This method is slightly more powerful than the Get Tasks method because it allows filtering by multiple process or task variables of types String, Number or Boolean. The size of the result set can be retrieved by using the Get Task Count (POST) method.

Security Consideration: There are several parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.

Authorizations:

basicAuth

query Parameters

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

Request Body schema: application/json

taskId	string or null Restrict to task with the given id.
taskIdIn	Array of strings or null Restrict to tasks with any of the given ids.
processInstanceId	string or null Restrict to tasks that belong to process instances with the given id.
processInstanceIdIn	Array of strings or null Restrict to tasks that belong to process instances with the given ids.
processInstanceBusinessKey	string or null Restrict to tasks that belong to process instances with the given business key.
processInstanceBusinessKeyExpression	string or null Restrict to tasks that belong to process instances with the given business key which is described by an expression. See the user guide for more information on available functions.
processInstanceBusinessKeyIn	Array of strings or null Restrict to tasks that belong to process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike	string or null Restrict to tasks that have a process instance business key that has the parameter value as a substring.
processInstanceBusinessKeyLikeExpression	string or null Restrict to tasks that have a process instance business key that has the parameter value as a substring and is described by an expression. See the user guide for more information on available functions.
processDefinitionId	string or null Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey	string or null Restrict to tasks that belong to a process definition with the given key.
processDefinitionKeyIn	Array of strings or null Restrict to tasks that belong to a process definition with one of the given keys. The keys need to be in a comma-separated list.
processDefinitionName	string or null Restrict to tasks that belong to a process definition with the given name.
processDefinitionNameLike	string or null Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId	string or null Restrict to tasks that belong to an execution with the given id.
caseInstanceId	string or null Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey	string or null Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike	string or null Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId	string or null Restrict to tasks that belong to a case definition with the given id.
caseDefinitionKey	string or null Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName	string or null Restrict to tasks that belong to a case definition with the given name.
caseDefinitionNameLike	string or null Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId	string or null Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn	Array of strings or null Only include tasks which belong to one of the passed and comma-separated activity instance ids.
tenantIdIn	Array of strings or null Only include tasks which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean or null Default: false Only include tasks which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
assignee	string or null Restrict to tasks that the given user is assigned to.
assigneeExpression	string or null Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike	string or null Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression	string or null Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
assigneeIn	Array of strings or null Only include tasks which are assigned to one of the passed and comma-separated user ids.
assigneeNotIn	Array of strings or null Only include tasks which are not assigned to one of the passed and comma-separated user ids.
owner	string or null Restrict to tasks that the given user owns.
ownerExpression	string or null Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup	string or null Only include tasks that are offered to the given group.
candidateGroupLike	string or null Only include tasks that are offered to groups that have the parameter value as a substring.
candidateGroupExpression	string or null Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
candidateUser	string or null Only include tasks that are offered to the given user or to one of his groups.
candidateUserExpression	string or null Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
includeAssignedTasks	boolean or null Default: false Also include tasks that are assigned to users in candidate queries. Default is to only include tasks that are not assigned to any user if you query by candidate user or group(s).
involvedUser	string or null Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee).
involvedUserExpression	string or null Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
assigned	boolean or null Default: false If set to `true`, restricts the query to all tasks that are assigned.
unassigned	boolean or null Default: false If set to `true`, restricts the query to all tasks that are unassigned.
taskDefinitionKey	string or null Restrict to tasks that have the given key.
taskDefinitionKeyIn	Array of strings or null Restrict to tasks that have one of the given keys. The keys need to be in a comma-separated list.
taskDefinitionKeyLike	string or null Restrict to tasks that have a key that has the parameter value as a substring.
name	string or null Restrict to tasks that have the given name.
nameNotEqual	string or null Restrict to tasks that do not have the given name.
nameLike	string or null Restrict to tasks that have a name with the given parameter value as substring.
nameNotLike	string or null Restrict to tasks that do not have a name with the given parameter value as substring.
description	string or null Restrict to tasks that have the given description.
descriptionLike	string or null Restrict to tasks that have a description that has the parameter value as a substring.
priority	integer or null <int32> Restrict to tasks that have the given priority.
maxPriority	integer or null <int32> Restrict to tasks that have a lower or equal priority.
minPriority	integer or null <int32> Restrict to tasks that have a higher or equal priority.
dueDate	string or null <date-time> Restrict to tasks that are due on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.546+0200`.
dueDateExpression	string or null Restrict to tasks that are due on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
dueAfter	string or null <date-time> Restrict to tasks that are due after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.435+0200`.
dueAfterExpression	string or null Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
dueBefore	string or null <date-time> Restrict to tasks that are due before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.243+0200`.
dueBeforeExpression	string or null Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
withoutDueDate	boolean or null Default: false Only include tasks which have no due date. Value may only be `true`, as `false` is the default behavior.
followUpDate	string or null <date-time> Restrict to tasks that have a followUp date on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.342+0200`.
followUpDateExpression	string or null Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpAfter	string or null <date-time> Restrict to tasks that have a followUp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.542+0200`.
followUpAfterExpression	string or null Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpBefore	string or null Restrict to tasks that have a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.234+0200`.
followUpBeforeExpression	string or null Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpBeforeOrNotExistent	string or null <date-time> Restrict to tasks that have no followUp date or a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.432+0200`. The typical use case is to query all `active` tasks for a user for a given date.
followUpBeforeOrNotExistentExpression	string or null Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdOn	string or null <date-time> Restrict to tasks that were created on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.324+0200`.
createdOnExpression	string or null Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdAfter	string or null <date-time> Restrict to tasks that were created after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.342+0200`.
createdAfterExpression	string or null Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdBefore	string or null <date-time> Restrict to tasks that were created before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.332+0200`.
createdBeforeExpression	string or null Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
updatedAfter	string or null <date-time> Restrict to tasks that were updated after the given date. Every action that fires a task update event is considered as updating the task. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.332+0200`.
updatedAfterExpression	string or null Restrict to tasks that were updated after the date described by the given expression. Every action that fires a task update event is considered as updating the task. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
delegationState	string or null Enum: "PENDING" "RESOLVED" Restrict to tasks that are in the given delegation state. Valid values are `PENDING` and `RESOLVED`.
candidateGroups	Array of strings or null Restrict to tasks that are offered to any of the given candidate groups. Takes a comma-separated list of group names, so for example `developers,support,sales`.
candidateGroupsExpression	string or null Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to `java.util.List` of Strings.
withCandidateGroups	boolean or null Default: false Only include tasks which have a candidate group. Value may only be `true`, as `false` is the default behavior.
withoutCandidateGroups	boolean or null Default: false Only include tasks which have no candidate group. Value may only be `true`, as `false` is the default behavior.
withCandidateUsers	boolean or null Default: false Only include tasks which have a candidate user. Value may only be `true`, as `false` is the default behavior.
withoutCandidateUsers	boolean or null Default: false Only include tasks which have no candidate users. Value may only be `true`, as `false` is the default behavior.
active	boolean or null Default: false Only include active tasks. Value may only be `true`, as `false` is the default behavior.
suspended	boolean or null Default: false Only include suspended tasks. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null (VariableQueryParameterDto) A JSON array to only include tasks that have variables with certain values. The array consists of JSON objects with three properties `name`, `operator` and `value`. `name` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. `value` may be of type `String`, `Number` or `Boolean`. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
	Array of objects or null (VariableQueryParameterDto) A JSON array to only include tasks that belong to a process instance with variables with certain values. The array consists of JSON objects with three properties `name`, `operator` and `value`. `name` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. `value` may be of type `String`, `Number` or `Boolean`. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`; `notLike`. `key` and `value` may not contain underscore or comma characters.
	Array of objects or null (VariableQueryParameterDto) A JSON array to only include tasks that belong to a case instance with variables with certain values. The array consists of JSON objects with three properties `name`, `operator` and `value`. `name` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. `value` may be of type `String`, `Number` or `Boolean`. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean or null Default: false Match all variable names in this query case-insensitively. If set `variableName` and `variablename` are treated as equal.
variableValuesIgnoreCase	boolean or null Default: false Match all variable values in this query case-insensitively. If set `variableValue` and `variablevalue` are treated as equal.
parentTaskId	string or null Restrict query to all tasks that are sub tasks of the given task. Takes a task id.
orQueries	Array of objects or null (TaskQueryDto) A JSON array of nested task queries with OR semantics. A task matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a task must fulfill at least one predicate of each query (Conjunctive Normal Form). All task query properties can be used except for: `sorting`, `withCandidateGroups`, `withoutCandidateGroups`, `withCandidateUsers`, `withoutCandidateUsers` See the User guide for more information about OR queries.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

Example

POST `/task` Request Body 1

{"taskVariables": [{"name": "varName",
"value": "varValue",
"operator": "eq"
},
{"name": "anotherVarName",
"value": 30,
"operator": "neq"
}
],
"processInstanceBusinessKeyIn": "aBusinessKey,anotherBusinessKey",
"assigneeIn": "anAssignee,anotherAssignee",
"priority": 10,
"sorting": [{"sortBy": "dueDate",
"sortOrder": "asc"
},
{"sortBy": "processVariable",
"sortOrder": "desc",
"parameters": {"variable": "orderId",
"type": "String"
}
}
]
}

Response samples

200
400

Content type

application/json

Example

Status 200 response 1

[{"id": "anId",
"name": "aName",
"assignee": "anAssignee",
"created": "2013-01-23T13:42:42.453+0200",
"due": "2013-01-23T13:49:42.342+0200",
"followUp:": "2013-01-23T13:44:42.546+0200",
"lastUpdated:": "2013-01-23T13:44:42.546+0200",
"delegationState": "RESOLVED",
"description": "aDescription",
"executionId": "anExecution",
"owner": "anOwner",
"parentTaskId": "aParentId",
"priority": 10,
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"caseDefinitionId": "aCaseDefId",
"caseInstanceId": "aCaseInstId",
"caseExecutionId": "aCaseExecution",
"taskDefinitionKey": "aTaskDefinitionKey",
"suspended": false,
"formKey": "aFormKey",
"camundaFormRef": {"key": "aCamundaFormKey",
"binding": "version",
"version": 2
},
"tenantId": "aTenantId",
"taskState": "aTaskState"
}
]

Get List Count

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

Security Consideration: There are several query parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.

Authorizations:

basicAuth

query Parameters

taskId	string Restrict to task with the given id.
taskIdIn	string Restrict to tasks with any of the given ids.
processInstanceId	string Restrict to tasks that belong to process instances with the given id.
processInstanceIdIn	string Restrict to tasks that belong to process instances with the given ids.
processInstanceBusinessKey	string Restrict to tasks that belong to process instances with the given business key.
processInstanceBusinessKeyExpression	string Restrict to tasks that belong to process instances with the given business key which is described by an expression. See the user guide for more information on available functions.
processInstanceBusinessKeyIn	string Restrict to tasks that belong to process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike	string Restrict to tasks that have a process instance business key that has the parameter value as a substring.
processInstanceBusinessKeyLikeExpression	string Restrict to tasks that have a process instance business key that has the parameter value as a substring and is described by an expression. See the user guide for more information on available functions.
processDefinitionId	string Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey	string Restrict to tasks that belong to a process definition with the given key.
processDefinitionKeyIn	string Restrict to tasks that belong to a process definition with one of the given keys. The keys need to be in a comma-separated list.
processDefinitionName	string Restrict to tasks that belong to a process definition with the given name.
processDefinitionNameLike	string Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId	string Restrict to tasks that belong to an execution with the given id.
caseInstanceId	string Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey	string Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike	string Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId	string Restrict to tasks that belong to a case definition with the given id.
caseDefinitionKey	string Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName	string Restrict to tasks that belong to a case definition with the given name.
caseDefinitionNameLike	string Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId	string Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn	string Only include tasks which belong to one of the passed and comma-separated activity instance ids.
tenantIdIn	string Only include tasks which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean Default: false Only include tasks which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
assignee	string Restrict to tasks that the given user is assigned to.
assigneeExpression	string Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike	string Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression	string Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
assigneeIn	string Only include tasks which are assigned to one of the passed and comma-separated user ids.
assigneeNotIn	string Only include tasks which are not assigned to one of the passed and comma-separated user ids.
owner	string Restrict to tasks that the given user owns.
ownerExpression	string Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup	string Only include tasks that are offered to the given group.
candidateGroupLike	string Only include tasks that are offered to groups that have the parameter value as a substring.
candidateGroupExpression	string Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
candidateUser	string Only include tasks that are offered to the given user or to one of his groups.
candidateUserExpression	string Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
includeAssignedTasks	boolean Default: false Also include tasks that are assigned to users in candidate queries. Default is to only include tasks that are not assigned to any user if you query by candidate user or group(s).
involvedUser	string Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee).
involvedUserExpression	string Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
assigned	boolean Default: false If set to `true`, restricts the query to all tasks that are assigned.
unassigned	boolean Default: false If set to `true`, restricts the query to all tasks that are unassigned.
taskDefinitionKey	string Restrict to tasks that have the given key.
taskDefinitionKeyIn	string Restrict to tasks that have one of the given keys. The keys need to be in a comma-separated list.
taskDefinitionKeyLike	string Restrict to tasks that have a key that has the parameter value as a substring.
name	string Restrict to tasks that have the given name.
nameNotEqual	string Restrict to tasks that do not have the given name.
nameLike	string Restrict to tasks that have a name with the given parameter value as substring.
nameNotLike	string Restrict to tasks that do not have a name with the given parameter value as substring.
description	string Restrict to tasks that have the given description.
descriptionLike	string Restrict to tasks that have a description that has the parameter value as a substring.
priority	integer Restrict to tasks that have the given priority.
maxPriority	integer Restrict to tasks that have a lower or equal priority.
minPriority	integer Restrict to tasks that have a higher or equal priority.
dueDate	string Restrict to tasks that are due on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.546+0200`.
dueDateExpression	string Restrict to tasks that are due on the date described by the given expression. See the User Guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
dueAfter	string Restrict to tasks that are due after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.435+0200`.
dueAfterExpression	string Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
dueBefore	string Restrict to tasks that are due before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.243+0200`.
dueBeforeExpression	string Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
withoutDueDate	boolean Default: false Only include tasks which have no due date. Value may only be `true`, as `false` is the default behavior.
followUpDate	string Restrict to tasks that have a followUp date on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.342+0200`.
followUpDateExpression	string Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpAfter	string Restrict to tasks that have a followUp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.542+0200`.
followUpAfterExpression	string Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpBefore	string Restrict to tasks that have a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.234+0200`.
followUpBeforeExpression	string Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpBeforeOrNotExistent	string Restrict to tasks that have no followUp date or a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.432+0200`. The typical use case is to query all `active` tasks for a user for a given date.
followUpBeforeOrNotExistentExpression	string Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdOn	string Restrict to tasks that were created on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.324+0200`.
createdOnExpression	string Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdAfter	string Restrict to tasks that were created after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.342+0200`.
createdAfterExpression	string Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdBefore	string Restrict to tasks that were created before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.332+0200`.
createdBeforeExpression	string Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
updatedAfter	string Restrict to tasks that were updated after the given date. Every action that fires a task update event is considered as updating the task. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.332+0200`.
updatedAfterExpression	string Restrict to tasks that were updated after the date described by the given expression. Every action that fires a task update event is considered as updating the task. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
delegationState	string Enum: "PENDING" "RESOLVED" Restrict to tasks that are in the given delegation state. Valid values are `PENDING` and `RESOLVED`.
candidateGroups	string Restrict to tasks that are offered to any of the given candidate groups. Takes a comma-separated list of group names, so for example `developers,support,sales`.
candidateGroupsExpression	string Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to `java.util.List` of Strings.
withCandidateGroups	boolean Default: false Only include tasks which have a candidate group. Value may only be `true`, as `false` is the default behavior.
withoutCandidateGroups	boolean Default: false Only include tasks which have no candidate group. Value may only be `true`, as `false` is the default behavior.
withCandidateUsers	boolean Default: false Only include tasks which have a candidate user. Value may only be `true`, as `false` is the default behavior.
withoutCandidateUsers	boolean Default: false Only include tasks which have no candidate users. Value may only be `true`, as `false` is the default behavior.
active	boolean Default: false Only include active tasks. Value may only be `true`, as `false` is the default behavior.
suspended	boolean Default: false Only include suspended tasks. Value may only be `true`, as `false` is the default behavior.
taskVariables	string Only include tasks that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
processVariables	string Only include tasks that belong to process instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`; `notLike`. `key` and `value` may not contain underscore or comma characters.
caseInstanceVariables	string Only include tasks that belong to case instances that have variables with certain values. Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as String objects on server side. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Default: false Match all variable names in this query case-insensitively. If set `variableName` and `variablename` are treated as equal.
variableValuesIgnoreCase	boolean Default: false Match all variable values in this query case-insensitively. If set `variableValue` and `variablevalue` are treated as equal.
parentTaskId	string Restrict query to all tasks that are sub tasks of the given task. Takes a task id.
withCommentAttachmentInfo	boolean Default: false Check if task has attachments and/or comments. Value may only be `true`, as `false` is the default behavior. Adding the filter will do additional attachment and comments queries to the database, it might slow down the query in case of tables having high volume of data. This param is not considered for count queries

Responses

Response samples

200
400

Content type

application/json

{"count": 1
}

Get List Count (POST)

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

Security Consideration: There are several parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.

Authorizations:

basicAuth

Request Body schema: application/json

taskId	string or null Restrict to task with the given id.
taskIdIn	Array of strings or null Restrict to tasks with any of the given ids.
processInstanceId	string or null Restrict to tasks that belong to process instances with the given id.
processInstanceIdIn	Array of strings or null Restrict to tasks that belong to process instances with the given ids.
processInstanceBusinessKey	string or null Restrict to tasks that belong to process instances with the given business key.
processInstanceBusinessKeyExpression	string or null Restrict to tasks that belong to process instances with the given business key which is described by an expression. See the user guide for more information on available functions.
processInstanceBusinessKeyIn	Array of strings or null Restrict to tasks that belong to process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike	string or null Restrict to tasks that have a process instance business key that has the parameter value as a substring.
processInstanceBusinessKeyLikeExpression	string or null Restrict to tasks that have a process instance business key that has the parameter value as a substring and is described by an expression. See the user guide for more information on available functions.
processDefinitionId	string or null Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey	string or null Restrict to tasks that belong to a process definition with the given key.
processDefinitionKeyIn	Array of strings or null Restrict to tasks that belong to a process definition with one of the given keys. The keys need to be in a comma-separated list.
processDefinitionName	string or null Restrict to tasks that belong to a process definition with the given name.
processDefinitionNameLike	string or null Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId	string or null Restrict to tasks that belong to an execution with the given id.
caseInstanceId	string or null Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey	string or null Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike	string or null Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId	string or null Restrict to tasks that belong to a case definition with the given id.
caseDefinitionKey	string or null Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName	string or null Restrict to tasks that belong to a case definition with the given name.
caseDefinitionNameLike	string or null Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId	string or null Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn	Array of strings or null Only include tasks which belong to one of the passed and comma-separated activity instance ids.
tenantIdIn	Array of strings or null Only include tasks which belong to one of the passed and comma-separated tenant ids.
withoutTenantId	boolean or null Default: false Only include tasks which belong to no tenant. Value may only be `true`, as `false` is the default behavior.
assignee	string or null Restrict to tasks that the given user is assigned to.
assigneeExpression	string or null Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike	string or null Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression	string or null Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
assigneeIn	Array of strings or null Only include tasks which are assigned to one of the passed and comma-separated user ids.
assigneeNotIn	Array of strings or null Only include tasks which are not assigned to one of the passed and comma-separated user ids.
owner	string or null Restrict to tasks that the given user owns.
ownerExpression	string or null Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup	string or null Only include tasks that are offered to the given group.
candidateGroupLike	string or null Only include tasks that are offered to groups that have the parameter value as a substring.
candidateGroupExpression	string or null Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
candidateUser	string or null Only include tasks that are offered to the given user or to one of his groups.
candidateUserExpression	string or null Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
includeAssignedTasks	boolean or null Default: false Also include tasks that are assigned to users in candidate queries. Default is to only include tasks that are not assigned to any user if you query by candidate user or group(s).
involvedUser	string or null Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee).
involvedUserExpression	string or null Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
assigned	boolean or null Default: false If set to `true`, restricts the query to all tasks that are assigned.
unassigned	boolean or null Default: false If set to `true`, restricts the query to all tasks that are unassigned.
taskDefinitionKey	string or null Restrict to tasks that have the given key.
taskDefinitionKeyIn	Array of strings or null Restrict to tasks that have one of the given keys. The keys need to be in a comma-separated list.
taskDefinitionKeyLike	string or null Restrict to tasks that have a key that has the parameter value as a substring.
name	string or null Restrict to tasks that have the given name.
nameNotEqual	string or null Restrict to tasks that do not have the given name.
nameLike	string or null Restrict to tasks that have a name with the given parameter value as substring.
nameNotLike	string or null Restrict to tasks that do not have a name with the given parameter value as substring.
description	string or null Restrict to tasks that have the given description.
descriptionLike	string or null Restrict to tasks that have a description that has the parameter value as a substring.
priority	integer or null <int32> Restrict to tasks that have the given priority.
maxPriority	integer or null <int32> Restrict to tasks that have a lower or equal priority.
minPriority	integer or null <int32> Restrict to tasks that have a higher or equal priority.
dueDate	string or null <date-time> Restrict to tasks that are due on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.546+0200`.
dueDateExpression	string or null Restrict to tasks that are due on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
dueAfter	string or null <date-time> Restrict to tasks that are due after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.435+0200`.
dueAfterExpression	string or null Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
dueBefore	string or null <date-time> Restrict to tasks that are due before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.243+0200`.
dueBeforeExpression	string or null Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
withoutDueDate	boolean or null Default: false Only include tasks which have no due date. Value may only be `true`, as `false` is the default behavior.
followUpDate	string or null <date-time> Restrict to tasks that have a followUp date on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.342+0200`.
followUpDateExpression	string or null Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpAfter	string or null <date-time> Restrict to tasks that have a followUp date after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.542+0200`.
followUpAfterExpression	string or null Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpBefore	string or null Restrict to tasks that have a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.234+0200`.
followUpBeforeExpression	string or null Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
followUpBeforeOrNotExistent	string or null <date-time> Restrict to tasks that have no followUp date or a followUp date before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.432+0200`. The typical use case is to query all `active` tasks for a user for a given date.
followUpBeforeOrNotExistentExpression	string or null Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdOn	string or null <date-time> Restrict to tasks that were created on the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.324+0200`.
createdOnExpression	string or null Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdAfter	string or null <date-time> Restrict to tasks that were created after the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.342+0200`.
createdAfterExpression	string or null Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
createdBefore	string or null <date-time> Restrict to tasks that were created before the given date. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.332+0200`.
createdBeforeExpression	string or null Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
updatedAfter	string or null <date-time> Restrict to tasks that were updated after the given date. Every action that fires a task update event is considered as updating the task. By default, the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., `2013-01-23T14:42:45.332+0200`.
updatedAfterExpression	string or null Restrict to tasks that were updated after the date described by the given expression. Every action that fires a task update event is considered as updating the task. See the user guide for more information on available functions. The expression must evaluate to a `java.util.Date` or `org.joda.time.DateTime` object.
delegationState	string or null Enum: "PENDING" "RESOLVED" Restrict to tasks that are in the given delegation state. Valid values are `PENDING` and `RESOLVED`.
candidateGroups	Array of strings or null Restrict to tasks that are offered to any of the given candidate groups. Takes a comma-separated list of group names, so for example `developers,support,sales`.
candidateGroupsExpression	string or null Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to `java.util.List` of Strings.
withCandidateGroups	boolean or null Default: false Only include tasks which have a candidate group. Value may only be `true`, as `false` is the default behavior.
withoutCandidateGroups	boolean or null Default: false Only include tasks which have no candidate group. Value may only be `true`, as `false` is the default behavior.
withCandidateUsers	boolean or null Default: false Only include tasks which have a candidate user. Value may only be `true`, as `false` is the default behavior.
withoutCandidateUsers	boolean or null Default: false Only include tasks which have no candidate users. Value may only be `true`, as `false` is the default behavior.
active	boolean or null Default: false Only include active tasks. Value may only be `true`, as `false` is the default behavior.
suspended	boolean or null Default: false Only include suspended tasks. Value may only be `true`, as `false` is the default behavior.
	Array of objects or null (VariableQueryParameterDto) A JSON array to only include tasks that have variables with certain values. The array consists of JSON objects with three properties `name`, `operator` and `value`. `name` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. `value` may be of type `String`, `Number` or `Boolean`. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
	Array of objects or null (VariableQueryParameterDto) A JSON array to only include tasks that belong to a process instance with variables with certain values. The array consists of JSON objects with three properties `name`, `operator` and `value`. `name` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. `value` may be of type `String`, `Number` or `Boolean`. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`; `notLike`. `key` and `value` may not contain underscore or comma characters.
	Array of objects or null (VariableQueryParameterDto) A JSON array to only include tasks that belong to a case instance with variables with certain values. The array consists of JSON objects with three properties `name`, `operator` and `value`. `name` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. `value` may be of type `String`, `Number` or `Boolean`. Valid `operator` values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean or null Default: false Match all variable names in this query case-insensitively. If set `variableName` and `variablename` are treated as equal.
variableValuesIgnoreCase	boolean or null Default: false Match all variable values in this query case-insensitively. If set `variableValue` and `variablevalue` are treated as equal.
parentTaskId	string or null Restrict query to all tasks that are sub tasks of the given task. Takes a task id.
orQueries	Array of objects or null (TaskQueryDto) A JSON array of nested task queries with OR semantics. A task matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a task must fulfill at least one predicate of each query (Conjunctive Normal Form). All task query properties can be used except for: `sorting`, `withCandidateGroups`, `withoutCandidateGroups`, `withCandidateUsers`, `withoutCandidateUsers` See the User guide for more information about OR queries.
	Array of objects or null Apply sorting of the result

Responses

Request samples

Payload

Content type

application/json

Example

POST `/task` Request Body 1

{"taskVariables": [{"name": "varName",
"value": "varValue",
"operator": "eq"
},
{"name": "anotherVarName",
"value": 30,
"operator": "neq"
}
],
"processInstanceBusinessKeyIn": "aBusinessKey,anotherBusinessKey",
"assigneeIn": "anAssignee,anotherAssignee",
"priority": 10,
"sorting": [{"sortBy": "dueDate",
"sortOrder": "asc"
},
{"sortBy": "processVariable",
"sortOrder": "desc",
"parameters": {"variable": "orderId",
"type": "String"
}
}
]
}

Response samples

200
400

Content type

application/json

{"count": 1
}

Create

Creates a new task.

Authorizations:

basicAuth

Request Body schema: application/json

id	string or null The task id.
name	string or null The task name.
assignee	string or null The assignee's id.
owner	string or null The owner's id.
created	string or null <date-time> The date the task was created on. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
lastUpdated	string or null <date-time> The date the task was last updated. Every action that fires a task update event will update this property. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
due	string or null <date-time> The task's due date. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
followUp	string or null <date-time> The follow-up date for the task. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
delegationState	string or null Enum: "PENDING" "RESOLVED" The task's delegation state. Possible values are `PENDING` and `RESOLVED`.
description	string or null The task's description.
executionId	string or null The id of the execution the task belongs to.
parentTaskId	string or null The id the parent task, if this task is a subtask.
priority	integer or null <int32> The task's priority.
processDefinitionId	string or null The id of the process definition the task belongs to.
processInstanceId	string or null The id of the process instance the task belongs to.
caseExecutionId	string or null The id of the case execution the task belongs to.
caseDefinitionId	string or null The id of the case definition the task belongs to.
caseInstanceId	string or null The id of the case instance the task belongs to.
taskDefinitionKey	string or null The task's key.
suspended	boolean or null Whether the task belongs to a process instance that is suspended.
formKey	string or null If not `null`, the form key for the task.
	object (CamundaFormRef)
tenantId	string or null If not `null`, the tenant id of the task.

Responses

Request samples

Payload

Content type

application/json

{"id": "aTaskId",
"name": "My Task",
"description": "This have to be done very urgent",
"priority": 30,
"assignee": "peter",
"owner": "mary",
"delegationState": "PENDING",
"due": "2014-08-30T10:00:00.000+0200",
"followUp": "2014-08-25T10:00:00.000+0200",
"parentTaskId": "aParentTaskId",
"caseInstanceId": "aCaseInstanceId",
"tenantId": null
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Task Count By Candidate Group

Retrieves the number of tasks for each candidate group.

Authorizations:

basicAuth

Responses

Response samples

200
400
403

Content type

application/json

[{"groupName": null,
"taskCount": 1
},
{"groupName": "aGroupName",
"taskCount": 2
},
{"groupName": "anotherGroupName",
"taskCount": 3
}
]

Delete

Removes a task by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to be removed.

Responses

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get

Retrieves a task by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to be retrieved.

Responses

Response samples

200
404

Content type

application/json

Example

GET /task/anId Response

{"id": "anId",
"name": "aName",
"assignee": "anAssignee",
"created": "2013-01-23T13:42:42.000+0200",
"due": "2013-01-23T13:49:42.576+0200",
"followUp": "2013-01-23T13:44:42.437+0200",
"delegationState": "RESOLVED",
"description": "aDescription",
"executionId": "anExecution",
"owner": "anOwner",
"parentTaskId": "aParentId",
"priority": 42,
"processDefinitionId": "aProcDefId",
"processInstanceId": "aProcInstId",
"caseDefinitionId": "aCaseDefId",
"caseInstanceId": "aCaseInstId",
"caseExecutionId": "aCaseExecution",
"taskDefinitionKey": "aTaskDefinitionKey",
"suspended": false,
"formKey": "aFormKey",
"camundaFormRef": {"key": "aCamundaFormKey",
"binding": "version",
"version": 2
},
"tenantId": "aTenantId",
"taskState": "aTaskState"
}

Update

Updates a task.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to be updated.

Request Body schema: application/json

id	string or null The task id.
name	string or null The task name.
assignee	string or null The assignee's id.
owner	string or null The owner's id.
created	string or null <date-time> The date the task was created on. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
lastUpdated	string or null <date-time> The date the task was last updated. Every action that fires a task update event will update this property. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
due	string or null <date-time> The task's due date. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
followUp	string or null <date-time> The follow-up date for the task. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
delegationState	string or null Enum: "PENDING" "RESOLVED" The task's delegation state. Possible values are `PENDING` and `RESOLVED`.
description	string or null The task's description.
executionId	string or null The id of the execution the task belongs to.
parentTaskId	string or null The id the parent task, if this task is a subtask.
priority	integer or null <int32> The task's priority.
processDefinitionId	string or null The id of the process definition the task belongs to.
processInstanceId	string or null The id of the process instance the task belongs to.
caseExecutionId	string or null The id of the case execution the task belongs to.
caseDefinitionId	string or null The id of the case definition the task belongs to.
caseInstanceId	string or null The id of the case instance the task belongs to.
taskDefinitionKey	string or null The task's key.
suspended	boolean or null Whether the task belongs to a process instance that is suspended.
formKey	string or null If not `null`, the form key for the task.
	object (CamundaFormRef)
tenantId	string or null If not `null`, the tenant id of the task.

Responses

Request samples

Payload

Content type

application/json

{"name": "My Task",
"description": "This have to be done very urgent",
"priority": 30,
"assignee": "peter",
"owner": "mary",
"delegationState": "PENDING",
"due": "2014-08-30T10:00:00.000+0200",
"followUp": "2014-08-25T10:00:00.000+0200",
"parentTaskId": "aParentTaskId",
"caseInstanceId": "aCaseInstanceId",
"tenantId": "tenantId"
}

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Set Assignee

Changes the assignee of a task to a specific user.

Note: The difference with the Claim Task method is that this method does not check if the task already has a user assigned to it.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to set the assignee for.

Request Body schema: application/json

Provide the id of the user that will be the assignee of the task.

userId

string or null

The id of the user that the current action refers to.

Responses

Request samples

Payload

Content type

application/json

POST /task/anId/assignee

{"userId": "aUserId"
}

Response samples

500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Handle BPMN Error

Reports a business error in the context of a running task by id. The error code must be specified to identify the BPMN error handler. See the documentation for Reporting Bpmn Error in User Tasks.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task a BPMN error is reported for.

Request Body schema: application/json

errorCode	string or null An error code that indicates the predefined error. It is used to identify the BPMN error handler.
errorMessage	string or null An error message that describes the error.
	object or null A JSON object containing variable key-value pairs.

Responses

Request samples

Payload

Content type

application/json

POST /task/aTaskId/bpmnError

{"errorCode": "bpmn-error-543",
"errorMessage": "anErrorMessage",
"variables": {"aVariable": {"value": "aStringValue",
"type": "String"
},
"anotherVariable": {"value": true,
"type": "Boolean"
}
}
}

Response samples

400
403
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Handle BPMN Escalation

Reports an escalation in the context of a running task by id. The escalation code must be specified to identify the escalation handler. See the documentation for Reporting Bpmn Escalation in User Tasks.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task in which context a BPMN escalation is reported.

Request Body schema: application/json

escalationCode	string or null An escalation code that indicates the predefined escalation. It is used to identify the BPMN escalation handler.
	object or null A JSON object containing variable key-value pairs.

Responses

Request samples

Payload

Content type

application/json

POST /task/aTaskId/bpmnEscalation

{"escalationCode": "bpmn-escalation-432",
"variables": {"aVariable": {"value": "aStringValue",
"type": "String"
},
"anotherVariable": {"value": true,
"type": "Boolean"
}
}
}

Response samples

400
403
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Claim

Claims a task for a specific user.

Note: The difference with the Set Assignee method is that here a check is performed to see if the task already has a user assigned to it.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to claim.

Request Body schema: application/json

Provide the id of the user that claims the task.

userId

string or null

The id of the user that the current action refers to.

Responses

Request samples

Payload

Content type

application/json

POST /task/anId/claim

{"userId": "aUserId"
}

Response samples

500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Complete

Completes a task and updates process variables.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to complete.

Request Body schema: application/json

	object or null A JSON object containing variable key-value pairs.
withVariablesInReturn	boolean or null Default: false Indicates whether the response should contain the process variables or not. The default is `false` with a response code of `204`. If set to `true` the response contains the process variables and has a response code of `200`. If the task is not associated with a process instance (e.g. if it's part of a case instance) no variables will be returned.

Responses

Request samples

Payload

Content type

application/json

Example

POST `/task/anId/complete`

Complete Task with variables in return

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

Response samples

200
400
500

Content type

application/json

Response Body

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

Delegate

Delegates a task to another user.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to delegate.

Request Body schema: application/json

Provide the id of the user that the task should be delegated to.

userId

string or null

The id of the user that the current action refers to.

Responses

Request samples

Payload

Content type

application/json

POST /task/anId/delegate

{"userId": "aUserId"
}

Response samples

500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Deployed Form

Retrieves the deployed form that is referenced from a given task. For further information please refer to the User Guide.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to get the deployed form for.

Responses

Response samples

200
400
403
404

Content type

application/xhtml+xml

Resonse for GET /task/taskId/deployed-form

<form role="form" name="invoiceForm"
                                            class="form-horizontal">
                                        <div class="form-group">
                                          <label class="control-label col-md-4"
                                                 for="creditor">Creditor</label>
                                          <div class="col-md-8">
                                            <input cam-variable-name="creditor"
                                                   cam-variable-type="String"
                                                   id="creditor"
                                                   class="form-control"
                                                   type="text"
                                                   required />
                                            <div class="help">
                                            (e.g. &quot;Great Pizza for Everyone Inc.&quot;)
                                            </div>
                                          </div>
                                        </div>
                                      </form>

Get Form Key

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to retrieve the form for.

Responses

Response samples

200
400

Content type

application/json

GET /task/anId/form

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

Get Task Form Variables

Retrieves the form variables for a task. The form variables take form data specified on the task into account. If form fields are defined, the variable types and default values of the form fields are taken into account.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to retrieve the variables for.

query Parameters

variableNames

string

A comma-separated list of variable names. Allows restricting the list of requested variables to the variable names in the list. It is best practice to restrict the list of variables to the variables actually required by the form in order to minimize fetching of data. If the query parameter is ommitted all variables are fetched. If the query parameter contains non-existent variable names, the variable names are ignored.

deserializeValues

boolean

Default: true

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

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

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

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

Responses

Response samples

200
404

Content type

application/json

GET /task/anId/form-variables

{"amount": {"type": "integer",
"value": 5,
"valueInfo": { }
},
"firstName": {"type": "String",
"value": "Jonny",
"valueInfo": { }
}
}

Get Rendered Form

Retrieves the rendered form for a task. This method can be used to get the HTML rendering of a Generated Task Form.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to get the rendered form for.

Responses

Response samples

200
400

Content type

application/xhtml+xml

A /task/anId/rendered-form HTML GET response body providing the rendered (generated) form content.

<form class="form-horizontal">
                                  <div class="control-group">
                                    <label class="control-label">Customer ID</label>
                                    <div class="controls">
                                      <input form-field type="string" name="customerId"></input>
                                    </div>
                                  </div>
                                  <div class="control-group">
                                    <label class="control-label">Amount</label>
                                    <div class="controls">
                                      <input form-field type="number" name="amount"></input>
                                    </div>
                                  </div>
                                </form>

Resolve

Resolves a task and updates execution variables.

Resolving a task marks that the assignee is done with the task delegated to them, and that it can be sent back to the owner. Can only be executed when the task has been delegated. The assignee will be set to the owner, who performed the delegation.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to resolve.

Request Body schema: application/json

	object or null A JSON object containing variable key-value pairs.
withVariablesInReturn	boolean or null Default: false Indicates whether the response should contain the process variables or not. The default is `false` with a response code of `204`. If set to `true` the response contains the process variables and has a response code of `200`. If the task is not associated with a process instance (e.g. if it's part of a case instance) no variables will be returned.

Responses

Request samples

Payload

Content type

application/json

POST /task/anId/resolve

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

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Submit Form

Completes a task and updates process variables using a form submit. There are two difference between this method and the complete method:

If the task is in state PENDING - i.e., has been delegated before, it is not completed but resolved. Otherwise it will be completed.
If the task has Form Field Metadata defined, the process engine will perform backend validation for any form fields which have validators defined. See the Generated Task Forms section of the User Guide for more information.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to submit the form for.

Request Body schema: application/json

	object or null A JSON object containing variable key-value pairs.
withVariablesInReturn	boolean or null Default: false Indicates whether the response should contain the process variables or not. The default is `false` with a response code of `204`. If set to `true` the response contains the process variables and has a response code of `200`. If the task is not associated with a process instance (e.g. if it's part of a case instance) no variables will be returned.

Responses

Request samples

Payload

Content type

application/json

Example

Request Body 1

POST /task/anId/submit-form

{"variables": {"aVariable": {"value": "aStringValue"
},
"anotherVariable": {"value": 42
},
"aThirdVariable": {"value": true
},
"aFileVariable": {"value": "TG9yZW0gaXBzdW0=",
"type": "File",
"valueInfo": {"filename": "myFile.txt"
}
}
}
}

Response samples

200
400
500

Content type

application/json

Response of a submitted task form with variables in return

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

Unclaim

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to unclaim.

Responses

Response samples

500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Task Attachment

Get List

Gets the attachments for a task.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to retrieve the attachments for.

Responses

Response samples

200
404

Content type

application/json

[{"id": "attachmentId",
"name": "attachmentName",
"taskId": "aTaskId",
"description": "attachmentDescription",
"type": "attachmentType",
"url": "http://my-attachment-content-url.de",
"createTime": "2017-02-10T14:33:19.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
},
{"id": "anotherAttachmentId",
"name": "anotherAttachmentName",
"taskId": "aTaskId",
"description": "anotherAttachmentDescription",
"type": "anotherAttachmentType",
"url": "http://my-another-attachment-content-url.de",
"createTime": "2017-02-10T14:33:19.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
},
{"id": "yetAnotherAttachmentId",
"name": "yetAnotherAttachmentName",
"taskId": "aTaskId",
"description": "yetAnotherAttachmentDescription",
"type": "yetAnotherAttachmentType",
"url": "http://yet-another-attachment-content-url.de",
"createTime": "2017-02-10T14:33:19.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Create

Creates an attachment for a task.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to add the attachment to.

Request Body schema: multipart/form-data

attachment-name	string or null The name of the attachment.
attachment-description	string or null The description of the attachment.
attachment-type	string or null The type of the attachment.
url	string or null The url to the remote content of the attachment.
content	string or null <binary> The content of the attachment.

Responses

Request samples

Payload

Content type

multipart/form-data

Post data for a new task attachment.

------------------------------925df49a954b
                        Content-Disposition: form-data; name="url"

                        http://my-attachment-content-url.de
                        ------------------------------925df49a954b
                        Content-Disposition: form-data; name="attachment-name"

                        attachmentName
                        ------------------------------925df49a954b
                        Content-Disposition: form-data; name="attachment-description"

                        attachmentDescription
                        ------------------------------925df49a954b
                        Content-Disposition: form-data; name="attachment-type"

                        attachmentType
                        ------------------------------925df49a954b--

Response samples

200
400
403

Content type

application/json

{"id": "attachmentId",
"name": "attachmentName",
"taskId": "aTaskId",
"description": "attachmentDescription",
"type": "attachmentType",
"url": "http://my-attachment-content-url.de",
"createTime": "2017-02-10T14:33:19.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"links": [{"method": "GET",
"href": "http://localhost:38080/rest-test/task/aTaskId/attachment/aTaskAttachmentId",
"rel": "self"
}
]
}

Delete

Removes an attachment from a task by id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task.
attachmentId required	string The id of the attachment to be removed.

Responses

Response samples

403
404

Content type

application/json

{"userId": "string",
"missingAuthorizations": [{"permissionName": "string",
"resourceName": "string",
"resourceId": "string"
}
],
"type": "string",
"message": "string",
"code": 0
}

Get

Retrieves a task attachment by task id and attachment id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task.
attachmentId required	string The id of the attachment to be retrieved.

Responses

Response samples

200
404

Content type

application/json

{"id": "attachmentId",
"name": "attachmentName",
"taskId": "aTaskId",
"description": "attachmentDescription",
"type": "attachmentType",
"url": "http://my-attachment-content-url.de",
"createTime": "2017-02-10T14:33:19.000+0200",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId",
"links": [{"method": "GET",
"href": "http://localhost:38080/rest-test/task/aTaskId/attachment/aTaskAttachmentId",
"rel": "self"
}
]
}

Get (Binary)

Retrieves the binary content of a task attachment by task id and attachment id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task.
attachmentId required	string The id of the attachment to be retrieved.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Task Comment

Get List

Gets the comments for a task by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to retrieve the comments for.

Responses

Response samples

200
404

Content type

application/json

[{"id": "commentId",
"userId": "userId",
"taskId": "aTaskId",
"processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687",
"time": "2013-01-02T21:37:03.764+0200",
"message": "message",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
},
{"id": "anotherCommentId",
"userId": "anotherUserId",
"taskId": "aTaskId",
"processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687",
"time": "2013-02-23T20:37:43.975+0200",
"message": "anotherMessage",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
},
{"id": "yetAnotherCommentId",
"userId": "yetAnotherUserId",
"taskId": "aTaskId",
"processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687",
"time": "2013-04-21T10:15:23.764+0200",
"message": "yetAnotherMessage",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}
]

Create

Creates a comment for a task by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to add the comment to.

Request Body schema: application/json

Note: Only the message and processInstanceId properties will be used. Every other property passed to this endpoint will be ignored.

id	string or null The id of the task comment.
userId	string or null The id of the user who created the comment.
taskId	string or null The id of the task to which the comment belongs.
processInstanceId	string or null The id of the process instance the comment is related to.
time	string or null <date-time> The time when the comment was created. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
message	string or null The content of the comment.
removalTime	string or null <date-time> The time after which the comment should be removed by the History Cleanup job. Default format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
rootProcessInstanceId	string or null The process instance id of the root process instance that initiated the process containing the task.
	Array of objects or null (AtomLink) The links associated to this resource, with `method`, `href` and `rel`.

Responses

Request samples

Payload

Content type

application/json

{"message": "a task comment",
"processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687"
}

Response samples

200
400
403

Content type

application/json

{"links": [{"method": "GET",
"href": "http://localhost:38080/rest-test/task/aTaskId/comment/aTaskCommentId",
"rel": "self"
}
],
"id": "aTaskCommentId",
"userId": "userId",
"taskId": "aTaskId",
"processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687",
"time": "2013-01-02T21:37:03.887+0200",
"message": "comment message",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}

Get

Retrieves a task comment by task id and comment id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task.
commentId required	string The id of the comment to be retrieved.

Responses

Response samples

200
404

Content type

application/json

{"id": "aTaskCommentId",
"userId": "userId",
"taskId": "aTaskId",
"processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687",
"time": "2013-01-02T21:37:03.664+0200",
"message": "comment content",
"removalTime": "2018-02-10T14:33:19.000+0200",
"rootProcessInstanceId": "aRootProcessInstanceId"
}

Task Identity Link

Get List

Gets the identity links for a task by id, which are the users and groups that are in some relation to it (including assignee and owner).

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to retrieve the identity links for.

query Parameters

type	string Filter by the type of links to include.

Responses

Response samples

200
400

Content type

application/json

[{"userId": "userId",
"groupId": null,
"type": "assignee"
},
{"userId": null,
"groupId": "groupId1",
"type": "candidate"
},
{"userId": null,
"groupId": "groupId2",
"type": "candidate"
}
]

Add

Adds an identity link to a task by id. Can be used to link any user or group to a task and specify a relation.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to add a link to.

Request Body schema: application/json

userId	string or null The id of the user participating in this link. Either `userId` or `groupId` is set.
groupId	string or null The id of the group participating in this link. Either `groupId` or `userId` is set.
type required	string or null The type of the identity link. The value of the this property can be user-defined. The Process Engine provides three pre-defined Identity Link `type`s: `candidate` `assignee` - reserved for the task assignee `owner` - reserved for the task owner Note: When adding or removing an Identity Link, the `type` property must be defined.

Responses

Request samples

Payload

Content type

application/json

{"groupId": "aNewGroupId",
"type": "candidate"
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete

Removes an identity link from a task by id

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to remove a link from.

Request Body schema: application/json

userId	string or null The id of the user participating in this link. Either `userId` or `groupId` is set.
groupId	string or null The id of the group participating in this link. Either `groupId` or `userId` is set.
type required	string or null The type of the identity link. The value of the this property can be user-defined. The Process Engine provides three pre-defined Identity Link `type`s: `candidate` `assignee` - reserved for the task assignee `owner` - reserved for the task owner Note: When adding or removing an Identity Link, the `type` property must be defined.

Responses

Request samples

Payload

Content type

application/json

{"groupId": "theOldGroupId",
"type": "candidate"
}

Response samples

400

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Task Local Variable

Get Local Task Variables

Retrieves all variables of a given task by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to retrieve the variables from.

query Parameters

deserializeValues

boolean

Default: true

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

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

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

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

Responses

Response samples

200
500

Content type

application/json

Example

GET `/task/aTaskId/variables`

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

Update/Delete Local Task Variables

Updates or deletes the variables in the context of a task. Updates precede deletions. So, if a variable is updated AND deleted, the deletion overrides the update.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to set variables for.

Request Body schema: application/json

	object or null A JSON object containing variable key-value pairs.
deletions	Array of strings or null An array of String keys of variables to be deleted.

Responses

Request samples

Payload

Content type

application/json

Status 204 Response: No content.

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

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete Local Task Variable

Removes a local variable from a task by id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to delete the variable from.
varName required	string The name of the variable to be removed.

Responses

Response samples

500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Local Task Variable

Retrieves a variable from the context of a given task by id.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to retrieve the variable from.
varName required	string The name of the variable to get

query Parameters

deserializeValue

boolean

Default: true

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

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

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

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

Responses

Response samples

200
404
500

Content type

application/json

Example

GET `/task/aTaskId/variables/myObject123`

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

Update Local Task Variable

Sets a variable in the context of a given task.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to set the variable for.
varName required	string The name of the variable to set.

Request Body schema: application/json

value	any (AnyValue) Can be any value - string, number, boolean, array or object. Note: Not every endpoint supports every type.
type	string or null The value type of the variable.
	object A JSON object containing additional, value-type-dependent properties. For serialized variables of type Object, the following properties can be provided: `objectTypeName`: A string representation of the object's type name. `serializationDataFormat`: The serialization format used to store the variable. For serialized variables of type File, the following properties can be provided: `filename`: The name of the file. This is not the variable name but the name that will be used when downloading the file again. `mimetype`: The MIME type of the file that is being uploaded. `encoding`: The encoding of the file that is being uploaded. The following property can be provided for all value types: `transient`: Indicates whether the variable should be transient or not. See documentation for more informations. (Not applicable for `decision-definition`, `/process-instance/variables-async`, and `/migration/executeAsync` endpoints)

Responses

Request samples

Payload

Content type

application/json

Example

PUT /task/aTaskId/variables/aVarName

Status 204. No content.

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

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Local Task Variable (Binary)

Retrieves a binary variable from the context of a given task by id. Applicable for byte array and file variables.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to retrieve the variable for.
varName required	string The name of the variable to retrieve.

Responses

Response samples

200
400
404

Content type

application/octet-stream

binary variable: Status 200. Content-Type: application/octet-stream

Update Local Task Variable (Binary)

Sets the serialized value for a binary variable or the binary value for a file variable.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to retrieve the variable for.
varName required	string The name of the variable to retrieve.

Request Body schema: multipart/form-data

For binary variables a multipart form submit with the following parts:

data	string or null <binary> The binary data to be set. For File variables, this multipart can contain the filename, binary value and MIME type of the file variable to be set Only the filename is mandatory.
valueType	string or null Enum: "Bytes" "File" The name of the variable type. Either Bytes for a byte array variable or File for a file variable.

Responses

Request samples

Payload

Content type

multipart/form-data

Example

POST `/task/aTaskId/variables/aVarName/data` (1)

Post binary content of a byte array variable.


                        ```
                        ------------------------------354ddb6baeff
                        Content-Disposition: form-data; name="data"; filename="image.png"
                        Content-Type: application/octet-stream
                        Content-Transfer-Encoding: binary

                        <<Byte Stream ommitted>>
                        ------------------------------354ddb6baeff
                        Content-Disposition: form-data; name="valueType"
                        Content-Type: text/plain; charset=US-ASCII
                        Content-Transfer-Encoding: 8bit

                        Bytes
                        ------------------------------1e838f8f632a--
                        ```

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Task Variable

Get Task Variables

Retrieves all variables visible from the task. A variable is visible from the task if it is a local task variable or declared in a parent scope of the task. See documentation on visiblity of variables.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to retrieve the variables from.

query Parameters

deserializeValues

boolean

Default: true

Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on the server side (default true). If set to true, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath.

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

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

Responses

Response samples

200
500

Content type

application/json

Example

GET `/task/aTaskId/variables`

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

Update/Delete Task Variables

Updates or deletes the variables visible from the task. Updates precede deletions. So, if a variable is updated AND deleted, the deletion overrides the update. A variable is visible from the task if it is a local task variable or declared in a parent scope of the task. See documentation on visiblity of variables.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the task to set variables for.

Request Body schema: application/json

	object or null A JSON object containing variable key-value pairs.
deletions	Array of strings or null An array of String keys of variables to be deleted.

Responses

Request samples

Payload

Content type

application/json

Status 204 Response: No content.

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

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete Task Variable

Removes a variable that is visible to a task. A variable is visible to a task if it is a local task variable or declared in a parent scope of the task. See documentation on visiblity of variables.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to delete the variable from.
varName required	string The name of the variable to be removed.

Responses

Response samples

500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Task Variable

Retrieves a variable from the context of a given task. The variable must be visible from the task. It is visible from the task if it is a local task variable or declared in a parent scope of the task. See documentation on visiblity of variables.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to retrieve the variable from.
varName required	string The name of the variable to get.

query Parameters

deserializeValue

boolean

Default: true

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

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

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

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

Responses

Response samples

200
404
500

Content type

application/json

Example

GET `/task/aTaskId/variables/myObject123`

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

Update Task Variable

Updates a process variable that is visible from the Task scope. A variable is visible from the task if it is a local task variable, or declared in a parent scope of the task. See the documentation on variable scopes and visibility.

Note: If a variable doesn't exist, the variable is created in the top-most scope visible from the task.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to set the variable for.
varName required	string The name of the variable to set.

Request Body schema: application/json

value	any (AnyValue) Can be any value - string, number, boolean, array or object. Note: Not every endpoint supports every type.
type	string or null The value type of the variable.
	object A JSON object containing additional, value-type-dependent properties. For serialized variables of type Object, the following properties can be provided: `objectTypeName`: A string representation of the object's type name. `serializationDataFormat`: The serialization format used to store the variable. For serialized variables of type File, the following properties can be provided: `filename`: The name of the file. This is not the variable name but the name that will be used when downloading the file again. `mimetype`: The MIME type of the file that is being uploaded. `encoding`: The encoding of the file that is being uploaded. The following property can be provided for all value types: `transient`: Indicates whether the variable should be transient or not. See documentation for more informations. (Not applicable for `decision-definition`, `/process-instance/variables-async`, and `/migration/executeAsync` endpoints)

Responses

Request samples

Payload

Content type

application/json

Example

PUT /task/aTaskId/variables/aVarName

Status 204. No content.

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

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Task Variable (Binary)

Retrieves a binary variable from the context of a given task. Applicable for byte array and file variables. The variable must be visible from the task. It is visible from the task if it is a local task variable or declared in a parent scope of the task. See documentation on visiblity of variables.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to retrieve the variable for.
varName required	string The name of the variable to retrieve.

Responses

Response samples

200
400
404

Content type

application/octet-stream

binary variable: Status 200. Content-Type: application/octet-stream

Update Task Variable (Binary)

Sets the serialized value for a binary variable or the binary value for a file variable visible from the task. A variable is visible from the task if it is a local task variable or declared in a parent scope of the task. See documentation on visiblity of variables.

Authorizations:

basicAuth

path Parameters

id required	string The id of the task to retrieve the variable for.
varName required	string The name of the variable to retrieve.

Request Body schema: multipart/form-data

For binary variables a multipart form submit with the following parts:

data	string or null <binary> The binary data to be set. For File variables, this multipart can contain the filename, binary value and MIME type of the file variable to be set Only the filename is mandatory.
valueType	string or null Enum: "Bytes" "File" The name of the variable type. Either Bytes for a byte array variable or File for a file variable.

Responses

Request samples

Payload

Content type

multipart/form-data

Example

POST `/task/aTaskId/variables/aVarName/data` (1)

Post binary content of a byte array variable.


                        ```
                        ------------------------------354ddb6baeff
                        Content-Disposition: form-data; name="data"; filename="image.png"
                        Content-Type: application/octet-stream
                        Content-Transfer-Encoding: binary

                        <<Byte Stream ommitted>>
                        ------------------------------354ddb6baeff
                        Content-Disposition: form-data; name="valueType"
                        Content-Type: text/plain; charset=US-ASCII
                        Content-Transfer-Encoding: 8bit

                        Bytes
                        ------------------------------1e838f8f632a--
                        ```

Response samples

400
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Telemetry

Fetch Telemetry Configuration

Fetches Telemetry Configuration.

Authorizations:

basicAuth

Responses

Response samples

200
401

Content type

application/json

The Response content of a status 200

{"enableTelemetry": true
}

Configure Telemetry Deprecated

Deprecated: The sending telemetry feature is removed. Please remove the endpoint usages as they are no longer needed.

Authorizations:

basicAuth

Request Body schema: application/json

enableTelemetry

boolean or null

Specifies if the telemetry data should be sent or not.

Responses

Request samples

Payload

Content type

application/json

The content of the Request Body

{"enableTelemetry": true
}

Response samples

401

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Fetch Telemetry Data Deprecated

Deprecated: Always returns false. The sending telemetry feature is removed. Please remove the endpoint usages as they are no longer needed.

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

The Response content of a status 200

{"installation": "8343cc7a-8ad1-42d4-97d2-43452c0bdfa3",
"product": {"name": "Camunda BPM Runtime",
"version": "7.14.0",
"edition": "enterprise",
"internals": {"database": {"vendor": "h2",
"version": "1.4.190 (2015-10-11)"
},
"application-server": {"vendor": "Wildfly",
"version": "WildFly Full 19.0.0.Final (WildFly Core 11.0.0.Final) - 2.0.30.Final"
},
"jdk": {"version": "14.0.2",
"vendor": "Oracle Corporation"
},
"commands": {"StartProcessInstanceCmd": {"count": 40
},
"FetchExternalTasksCmd": {"count": 100
}
},
"metrics": {"process-instances": {"count": 936
},
"flow-node-instances": {"count": 6125
},
"decision-instances": {"count": 140
},
"executed-decision-elements": {"count": 732
}
},
"data-collection-start-date": "2022-11-320T15:53:20.386+0100",
"camunda-integration": ["spring-boot-starter",
"camunda-bpm-run"
],
"license-key": {"customer": "customer name",
"type": "UNIFIED",
"valid-until": "2022-09-30",
"unlimited": false,
"features": {"camundaBPM": "true"
},
"raw": "customer=customer name;expiryDate=2022-09-30;camundaBPM=true;optimize=false;cawemo=false"
},
"webapps": ["cockpit",
"admin"
]
}
}
}

Tenant

Get Tenants

Query for a list of tenants using a list of parameters. The size of the result set can be retrieved by using the Get Tenant Count method.

Authorizations:

basicAuth

query Parameters

sortBy	string Enum: "id" "name" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
id	string Filter by the id of the tenant.
name	string Filter by the name of the tenant.
nameLike	string Filter by the name that the parameter is a substring of.
userMember	string Select only tenants where the given user is a member of.
groupMember	string Select only tenants where the given group is a member of.
includingGroupsOfUser	boolean Select only tenants where the user or one of his groups is a member of. Can only be used in combination with the `userMember` parameter. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

GET /tenant?name=tenantOne

[{"id": "tenantOne",
"name": "Tenant One"
}
]

Tenant Resource Options

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

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

OPTIONS /tenant

{"links": [{"method": "GET",
"href": "http://localhost:8080/engine-rest/tenant",
"rel": "list"
},
{"method": "GET",
"href": "http://localhost:8080/engine-rest/tenant/count",
"rel": "count"
},
{"method": "POST",
"href": "http://localhost:8080/engine-rest/tenant/create",
"rel": "create"
}
]
}

Get Tenant Count

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

Authorizations:

basicAuth

query Parameters

id	string Filter by the id of the tenant.
name	string Filter by the name of the tenant.
nameLike	string Filter by the name that the parameter is a substring of.
userMember	string Select only tenants where the given user is a member of.
groupMember	string Select only tenants where the given group is a member of.
includingGroupsOfUser	boolean Select only tenants where the user or one of his groups is a member of. Can only be used in combination with the `userMember` parameter. Value may only be `true`, as `false` is the default behavior.

Responses

Response samples

200
400

Content type

application/json

GET /tenant/count?name=tenantOne

{"count": 1
}

Create Tenant

Create a new tenant.

Authorizations:

basicAuth

Request Body schema: application/json

id	string or null The id of the tenant.
name	string or null The name of the tenant.

Responses

Request samples

Payload

Content type

application/json

{"id": "tenantOne",
"name": "Tenant One"
}

Response samples

403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Delete Tenant

Deletes a tenant by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the tenant to be deleted.

Responses

Response samples

403
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Tenant

Retrieves a tenant.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the tenant to be retrieved.

Responses

Response samples

200
404

Content type

application/json

GET /tenant/tenantOne

{"id": "tenantOne",
"name": "Tenant One"
}

Tenant Resource Options

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

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the tenant

Responses

Response samples

200

Content type

application/json

OPTIONS /tenant/tenantOne

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

Update Tenant

Updates a given tenant.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the tenant.

Request Body schema: application/json

id	string or null The id of the tenant.
name	string or null The name of the tenant.

Responses

Request samples

Payload

Content type

application/json

{"id": "tenantOne",
"name": "Tenant One"
}

Response samples

403
404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Tenant Group Membership Resource Options

The OPTIONS request allows checking for the set of available operations that the currently authenticated user can perform on the resource. If the user can perform an operation or not may depend on various things, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the tenant

Responses

Response samples

200

Content type

application/json

OPTIONS /tenant/tenantOne/group-members

{"links": [{"method": "DELETE",
"href": "http://localhost:8080/engine-rest/tenant/tenantOne/group-members",
"rel": "delete"
},
{"method": "PUT",
"href": "http://localhost:8080/engine-rest/tenant/tenantOne/group-members",
"rel": "create"
}
]
}

Create Tenant Group Membership

Creates a membership between a tenant and a group.

Authorizations:

basicAuth

path Parameters

id required	string The id of the tenant.
groupId required	string The id of the group.

Responses

Response samples

403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Create Tenant Group Membership

Creates a membership between a tenant and a group.

Authorizations:

basicAuth

path Parameters

id required	string The id of the tenant.
groupId required	string The id of the group.

Responses

Response samples

403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Tenant User Membership Resource Options

The OPTIONS request allows checking for the set of available operations that the currently authenticated user can perform on the resource. If the user can perform an operation or not may depend on various things, including the users authorizations to interact with this resource and the internal configuration of the process engine.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the tenant

Responses

Response samples

200

Content type

application/json

OPTIONS /tenant/tenantOne/user-members

{"links": [{"method": "DELETE",
"href": "http://localhost:8080/engine-rest/tenant/tenantOne/user-members",
"rel": "delete"
},
{"method": "PUT",
"href": "http://localhost:8080/engine-rest/tenant/tenantOne/user-members",
"rel": "create"
}
]
}

Delete a Tenant User Membership

Deletes a membership between a tenant and an user.

Authorizations:

basicAuth

path Parameters

id required	string The id of the tenant.
userId required	string The id of the user.

Responses

Response samples

403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Create Tenant User Membership

Creates a membership between a tenant and an user.

Authorizations:

basicAuth

path Parameters

id required	string The id of the tenant.
userId required	string The id of the user.

Responses

Response samples

403
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

User

Get List

Query for a list of users using a list of parameters. The size of the result set can be retrieved by using the Get User Count method. Get User Count method.

Authorizations:

basicAuth

query Parameters

id	string Filter by user id
idIn	string Filter by a comma-separated list of user ids.
firstName	string Filter by the first name of the user. Exact match.
firstNameLike	string Filter by the first name that the parameter is a substring of.
lastName	string Filter by the last name of the user. Exact match.
lastNameLike	string Filter by the last name that the parameter is a substring of.
email	string Filter by the email of the user. Exact match.
emailLike	string Filter by the email that the parameter is a substring of.
memberOfGroup	string Filter for users which are members of the given group.
memberOfTenant	string Filter for users which are members of the given tenant.
potentialStarter	string Only select Users that are potential starter for the given process definition.
sortBy	string Enum: "userId" "firstName" "lastName" "email" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Responses

Response samples

200
400

Content type

application/json

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

Options

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

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

{"links": [{"method": "GET",
"href": "http://localhost:8080/engine-rest/user",
"rel": "list"
},
{"method": "GET",
"href": "http://localhost:8080/engine-rest/user/count",
"rel": "count"
},
{"method": "POST",
"href": "http://localhost:8080/engine-rest/user/create",
"rel": "create"
}
]
}

Get List Count

Queries for the number of deployments that fulfill given parameters. Takes the same parameters as the Get Users method.

Authorizations:

basicAuth

query Parameters

id	string Filter by user id
idIn	string Filter by a comma-separated list of user ids.
firstName	string Filter by the first name of the user. Exact match.
firstNameLike	string Filter by the first name that the parameter is a substring of.
lastName	string Filter by the last name of the user. Exact match.
lastNameLike	string Filter by the last name that the parameter is a substring of.
email	string Filter by the email of the user. Exact match.
emailLike	string Filter by the email that the parameter is a substring of.
memberOfGroup	string Filter for users which are members of the given group.
memberOfTenant	string Filter for users which are members of the given tenant.
potentialStarter	string Only select Users that are potential starter for the given process definition.

Responses

Response samples

200
400

Content type

application/json

{"count": 2
}

Create

Create a new user.

Authorizations:

basicAuth

Request Body schema: application/json

	object (UserProfileDto)
	object (UserCredentialsDto)

Responses

Request samples

Payload

Content type

application/json

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

Delete

Deletes a user by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the user to be deleted.

Responses

Response samples

403
404

Content type

application/json

null

Options

The /user resource supports two custom OPTIONS requests, one for the resource as such and one for individual user instances. The OPTIONS request allows checking for the set of available operations that the currently authenticated user can perform on the /user resource. If the user can perform an operation or not may depend on various things, including the user's authorizations to interact with this resource and the internal configuration of the process engine. OPTIONS /user/{id} returns available interactions on a resource instance.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the user to be deleted.

Responses

Response samples

200

Content type

application/json

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

Update Credentials

Updates a user's credentials (password)

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the user to be updated.

Request Body schema: application/json

password	string or null The users new password.
authenticatedUserPassword	string or null The password of the authenticated user who changes the password of the user (i.e., the user with passed id as path parameter).

Responses

Request samples

Payload

Content type

application/json

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

Response samples

400
403
404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Get Profile

Retrieves a user's profile.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the user to retrieve.

Responses

Response samples

200
404

Content type

application/json

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

Update User Profile

Updates the profile information of an already existing user.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the user.

Request Body schema: application/json

id	string or null The id of the user.
firstName	string or null The first name of the user.
lastName	string or null The first name of the user.
email	string or null The email of the user.

Responses

Request samples

Payload

Content type

application/json

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

Response samples

403
404
500

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Unlock User

Unlocks a user by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the user to be unlocked.

Responses

Response samples

403
404

Content type

application/json

null

Variable Instance

Get Variable Instances

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

Authorizations:

basicAuth

query Parameters

variableName	string Filter by variable instance name.
variableNameLike	string 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	string Only include variable instances which belong to one of the passed and comma-separated process instance ids.
executionIdIn	string Only include variable instances which belong to one of the passed and comma-separated execution ids.
caseInstanceIdIn	string Only include variable instances which belong to one of the passed and comma-separated case instance ids.
caseExecutionIdIn	string Only include variable instances which belong to one of the passed and comma-separated case execution ids.
taskIdIn	string Only include variable instances which belong to one of the passed and comma-separated task ids.
batchIdIn	string Only include variable instances which belong to one of the passed and comma-separated batch ids.
activityInstanceIdIn	string Only include variable instances which belong to one of the passed and comma-separated activity instance ids.
tenantIdIn	string Only include variable instances which belong to one of the passed and comma-separated tenant ids.
variableValues	string Only include variable instances that have the certain values. Value filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Match all variable names provided in `variableValues` case-insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match all variable values provided in `variableValues` case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
variableScopeIdIn	string Only include variable instances which belong to one of passed scope ids.
sortBy	string Enum: "variableName" "variableType" "activityInstanceId" "tenantId" Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter.
sortOrder	string Enum: "asc" "desc" 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	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
deserializeValues	boolean Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default `true`). If set to `true`, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to `false`, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML. Note: While `true` is the default value for reasons of backward compatibility, we recommend setting this parameter to `false` when developing web applications that are independent of the Java process applications deployed to the engine.

Responses

Response samples

200
400

Content type

application/json

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

[{"id": "someId",
"name": "amount",
"type": "Integer",
"value": 5,
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "aProcessInstanceId",
"executionId": "b68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"batchId": null,
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726",
"caseExecutionId": null,
"caseInstanceId": null,
"errorMessage": null,
"tenantId": null
},
{"id": "someOtherId",
"name": "amount",
"type": "Integer",
"value": 15,
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "aProcessInstanceId",
"executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"batchId": null,
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726",
"caseExecutionId": null,
"caseInstanceId": null,
"errorMessage": null,
"tenantId": null
},
{"id": "yetAnotherId",
"name": "amount",
"type": "Integer",
"value": 150,
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "anotherProcessInstanceId",
"executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"batchId": null,
"activityInstanceId": "Task_2:b68b71ca-e310-11e2-beb0-f0def1557726",
"caseExecutionId": null,
"caseInstanceId": null,
"errorMessage": null,
"tenantId": null
}
]

Get Variable Instances (POST)

Query for variable instances that fulfill given parameters through a JSON object. This method is slightly more powerful than the [Get Variable Instances](https://docs.camunda.org/manual/7.22/reference/rest/variable- instance/get-query/) method because it allows filtering by multiple variable instances of types String, Number or Boolean.

Authorizations:

basicAuth

query Parameters

firstResult	integer Pagination of results. Specifies the index of the first result to return.
maxResults	integer Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
deserializeValues	boolean Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default `true`). If set to `true`, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to `false`, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML. Note: While `true` is the default value for reasons of backward compatibility, we recommend setting this parameter to `false` when developing web applications that are independent of the Java process applications deployed to the engine.

Request Body schema: application/json

variableName	string or null Filter by variable instance name.
variableNameLike	string or null 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	Array of strings or null Only include variable instances which belong to one of the passed process instance ids.
executionIdIn	Array of strings or null Only include variable instances which belong to one of the passed execution ids.
caseInstanceIdIn	Array of strings or null Only include variable instances which belong to one of the passed case instance ids.
caseExecutionIdIn	Array of strings or null Only include variable instances which belong to one of the passed case execution ids.
taskIdIn	Array of strings or null Only include variable instances which belong to one of the passed task ids.
batchIdIn	Array of strings or null Only include variable instances which belong to one of the passed batch ids.
activityInstanceIdIn	Array of strings or null Only include variable instances which belong to one of the passed activity instance ids.
tenantIdIn	Array of strings or null Only include variable instances which belong to one of the passed tenant ids.
	Array of objects or null (VariableQueryParameterDto) An array to only include variable instances that have the certain values. The array consists of objects with the three properties `name`, `operator` and `value`. `name (String)` is the variable name, `operator (String)` is the comparison operator to be used and `value` the variable value. `value` may be `String`, `Number` or `Boolean`. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`
variableNamesIgnoreCase	boolean or null Match all variable names provided in `variableValues` case-insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match all variable values provided in `variableValues` case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
variableScopeIdIn	Array of strings or null Only include variable instances which belong to one of passed scope ids.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints

Responses

Request samples

Payload

Content type

application/json

{"variableValues": [{"name": "amount",
"operator": "gteq",
"value": 5
},
{"name": "amount",
"operator": "lteq",
"value": 200
}
],
"processInstanceIdIn": ["aProcessInstanceId",
"anotherProcessInstanceId"
],
"sorting": [{"sortBy": "variableType",
"sortOrder": "asc"
}
]
}

Response samples

200
400

Content type

application/json

POST /variable-instance

[{"id": "someId",
"name": "amount",
"type": "Integer",
"value": 5,
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "aProcessInstanceId",
"executionId": "b68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"batchId": null,
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726",
"errorMessage": null,
"tenantId": null
},
{"id": "someOtherId",
"name": "amount",
"type": "Integer",
"value": 15,
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "aProcessInstanceId",
"executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"batchId": null,
"activityInstanceId": "Task_1:b68b71ca-e310-11e2-beb0-f0def1557726",
"errorMessage": null,
"tenantId": null
},
{"id": "yetAnotherId",
"name": "amount",
"type": "Integer",
"value": 150,
"processDefinitionId": "aProcessDefinitionId",
"processInstanceId": "anotherProcessInstanceId",
"executionId": "68b71c9-e310-11e2-beb0-f0def1557726",
"taskId": null,
"batchId": null,
"activityInstanceId": "Task_2:b68b71ca-e310-11e2-beb0-f0def1557726",
"errorMessage": null,
"tenantId": null
}
]

Get Variable Instance Count

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

Authorizations:

basicAuth

query Parameters

variableName	string Filter by variable instance name.
variableNameLike	string 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	string Only include variable instances which belong to one of the passed and comma-separated process instance ids.
executionIdIn	string Only include variable instances which belong to one of the passed and comma-separated execution ids.
caseInstanceIdIn	string Only include variable instances which belong to one of the passed and comma-separated case instance ids.
caseExecutionIdIn	string Only include variable instances which belong to one of the passed and comma-separated case execution ids.
taskIdIn	string Only include variable instances which belong to one of the passed and comma-separated task ids.
batchIdIn	string Only include variable instances which belong to one of the passed and comma-separated batch ids.
activityInstanceIdIn	string Only include variable instances which belong to one of the passed and comma-separated activity instance ids.
tenantIdIn	string Only include variable instances which belong to one of the passed and comma-separated tenant ids.
variableValues	string Only include variable instances that have the certain values. Value filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form `key_operator_value`. `key` is the variable name, `operator` is the comparison operator to be used and `value` the variable value. Note: Values are always treated as `String` objects on server side. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`. `key` and `value` may not contain underscore or comma characters.
variableNamesIgnoreCase	boolean Match all variable names provided in `variableValues` case-insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean Match all variable values provided in `variableValues` case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
variableScopeIdIn	string Only include variable instances which belong to one of passed scope ids.

Responses

Response samples

200
400

Content type

application/json

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

{"count": 3
}

Get Variable Instance Count (POST)

Query for the number of variable instances that fulfill given parameters. This method takes the same message body as the [Get Variable Instances POST](https://docs.camunda.org/manual/7.22/reference/rest/variable- instance/post-query/) method and therefore it is slightly more powerful than the Get Variable Instance Count method.

Authorizations:

basicAuth

Request Body schema: application/json

variableName	string or null Filter by variable instance name.
variableNameLike	string or null 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	Array of strings or null Only include variable instances which belong to one of the passed process instance ids.
executionIdIn	Array of strings or null Only include variable instances which belong to one of the passed execution ids.
caseInstanceIdIn	Array of strings or null Only include variable instances which belong to one of the passed case instance ids.
caseExecutionIdIn	Array of strings or null Only include variable instances which belong to one of the passed case execution ids.
taskIdIn	Array of strings or null Only include variable instances which belong to one of the passed task ids.
batchIdIn	Array of strings or null Only include variable instances which belong to one of the passed batch ids.
activityInstanceIdIn	Array of strings or null Only include variable instances which belong to one of the passed activity instance ids.
tenantIdIn	Array of strings or null Only include variable instances which belong to one of the passed tenant ids.
	Array of objects or null (VariableQueryParameterDto) An array to only include variable instances that have the certain values. The array consists of objects with the three properties `name`, `operator` and `value`. `name (String)` is the variable name, `operator (String)` is the comparison operator to be used and `value` the variable value. `value` may be `String`, `Number` or `Boolean`. Valid operator values are: `eq` - equal to; `neq` - not equal to; `gt` - greater than; `gteq` - greater than or equal to; `lt` - lower than; `lteq` - lower than or equal to; `like`
variableNamesIgnoreCase	boolean or null Match all variable names provided in `variableValues` case-insensitively. If set to `true` variableName and variablename are treated as equal.
variableValuesIgnoreCase	boolean or null Match all variable values provided in `variableValues` case-insensitively. If set to `true` variableValue and variablevalue are treated as equal.
variableScopeIdIn	Array of strings or null Only include variable instances which belong to one of passed scope ids.
	Array of objects or null An array of criteria to sort the result by. Each element of the array is an object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. Sorting has no effect for `count` endpoints

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400

Content type

application/json

POST /variable-instance/count

{"count": 3
}

Get Variable Instance

Retrieves a variable by id.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the variable instance.

query Parameters

deserializeValue

boolean

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

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

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

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

Responses

Response samples

200
404

Content type

application/json

GET /variable-instance/someId

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

Get Variable Instance (Binary)

Retrieves the content of a variable by id. Applicable for byte array and file variables.

Authorizations:

basicAuth

path Parameters

id

required

string

The id of the variable instance.

Responses

Response samples

400
404

Content type

application/json

{"type": "string",
"message": "string",
"code": 0
}

Version

Get Rest API version

Retrieves the version of the Rest API.

Authorizations:

basicAuth

Responses

Response samples

200

Content type

application/json

The Response content of a status 200

{"version": "7.13.0"
}