Camunda Platform REST API (7.21.0-SNAPSHOT)

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

Content type
application/json

GET /authorization?userIdIn=jonny1,jonny2

[
  • {
    },
  • {
    }
]

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

Content type
application/json

OPTIONS /authorization

{}

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

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

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

Content type
application/json
{
  • "type": 0,
  • "permissions": [
    ],
  • "userId": "*",
  • "groupId": null,
  • "resourceType": 1,
  • "resourceId": "*"
}

Response samples

Content type
application/json

POST /authorization/create

{}

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

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

Content type
application/json

GET /authorization/anAuthorizationId

{
  • "id": "anAuthorizationId",
  • "type": 0,
  • "permissions": [
    ],
  • "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

Content type
application/json

OPTIONS /authorization/anAuthorizationId

{}

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

Content type
application/json
{
  • "permissions": 16,
  • "userId": "*",
  • "groupId": null,
  • "resourceType": 1,
  • "resourceId": "*"
}

Response samples

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

Content type
application/json

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

[
  • {
    }
]

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

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

Content type
application/json

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

[
  • {
    }
]

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

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

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

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

Content type
application/json
{
  • "suspended": true
}

Response samples

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

Content type
application/json

The content of the Request Body

{
  • "variables": {
    },
  • "businessKey": "aBusinessKey",
  • "tenantId": "aTenantId"
}

Response samples

Content type
application/json

The Response content of a status 200

[
  • {
    },
  • {
    }
]

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

Content type
application/json

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

[
  • {
    }
]

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

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

Content type
application/json

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

{
  • "id": "aDecisionDefinitionId",
  • "key": "dish-decision",
  • "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

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

Content type
application/json
{
  • "variables": {
    }
}

Response samples

Content type
application/json

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

[
  • {
    }
]

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

Content type
application/json
{
  • "historyTimeToLive": 5
}

Response samples

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

Content type
application/json

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

{
  • "id": "aDecisionDefinitionId",
  • "key": "dish-decision",
  • "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

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

Content type
application/json
{
  • "variables": {
    }
}

Response samples

Content type
application/json

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

[
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "historyTimeToLive": 5
}

Response samples

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

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

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

Content type
application/json

Response for GET /decision-definition/aDecisionDefinitionId

{
  • "id": "aDecisionDefinitionId",
  • "key": "dish-decision",
  • "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

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

Content type
application/json
{
  • "variables": {
    }
}

Response samples

Content type
application/json

Response for POST /decision-definition/aDecisionDefinitionId/evaluate

[
  • {
    }
]

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

Content type
application/json
{
  • "historyTimeToLive": 5
}

Response samples

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

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

Content type
application/json

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

[
  • {
    }
]

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

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

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

Content type

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

Response samples

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

Response samples

Content type

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

Response samples

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

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

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

Content type

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

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

Content type
application/json
[
  • {
    }
]

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

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

Content type
application/json
{
  • "links": [],
  • "id": "aDeploymentId",
  • "name": "aName",
  • "source": "process application",
  • "deploymentTime": "2013-01-23T13:59:43.000+0200",
  • "tenantId": null,
  • "deployedProcessDefinitions": {
    },
  • "deployedCaseDefinitions": null,
  • "deployedDecisionDefinitions": null,
  • "deployedDecisionRequirementsDefinitions": null
}

Get Registered Deployments

Queries the registered deployment IDs for the current application.

Authorizations:
basicAuth

Responses

Response samples

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

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

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

Content type
application/json
{
  • "resourceIds": [
    ],
  • "resourceNames": [
    ],
  • "source": "cockpit"
}

Response samples

Content type
application/json
{
  • "links": [],
  • "id": "aDeploymentId",
  • "name": "aName",
  • "source": "cockpit",
  • "deploymentTime": "2015-10-13T13:59:43.000+0200",
  • "tenantId": null,
  • "deployedProcessDefinitions": {
    },
  • "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

Content type
application/json
[
  • {
    },
  • {
    }
]

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

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

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

Content type
application/json
[
  • {
    },
  • {
    }
]

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

Content type
application/json
[
  • {
    },
  • {
    }
]

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

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

Content type
application/json

GET /execution?variables=myVariable_eq_camunda

[
  • {
    }
]

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

Content type
application/json
{
  • "variables": [
    ],
  • "processDefinitionId": "aProcessDefinitionId",
  • "sorting": [
    ]
}

Response samples

Content type
application/json

POST /execution

[
  • {
    }
]

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

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

Content type
application/json
{
  • "variables": [
    ],
  • "processDefinitionId": "aProcessDefinitionId"
}

Response samples

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

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

Content type
application/json
{
  • "incidentType": "aType",
  • "configuration": "aConfiguration"
}

Response samples

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

Content type
application/json
Example

GET /execution/anExecutionId/localVariables

{
  • "aVariableKey": {
    }
}

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

Content type
application/json
{
  • "modifications": {
    },
  • "deletions": [
    ]
}

Response samples

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

Content type
application/json
Example

GET /execution/anExecutionId/localVariables/aVarName

{
  • "value": {
    },
  • "type": "Object",
  • "valueInfo": {
    }
}

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

Content type
application/json
Example
{
  • "value": "someValue",
  • "type": "String"
}

Response samples

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

Content type
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

Content type
multipart/form-data
Example

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

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

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

Content type
application/json
{
  • "variables": {
    }
}

Response samples

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

Content type
application/json
{
  • "variables": {
    }
}

Response samples

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

Content type
application/json
[
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "processDefinitionId": "aProcessDefinitionId",
  • "sorting": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

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

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

Content type
application/json
{
  • "topicName": "aTopicName",
  • "withRetriesLeft": true
}

Response samples

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:

Responses

Request samples

Content type
application/json
Example

Request with variable filtering

{
  • "workerId": "aWorkerId",
  • "maxTasks": 2,
  • "usePriority": true,
  • "topics": [
    ]
}

Response samples

Content type
application/json
Example

Request with variable filtering

[
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "retries": 123,
  • "externalTaskIds": [
    ]
}

Response samples

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

Content type
application/json
{
  • "retries": 123,
  • "externalTaskIds": [
    ]
}

Response samples

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

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

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

Content type
application/json
{
  • "workerId": "aWorker",
  • "errorCode": "bpmn-error",
  • "errorMessage": "anErrorMessage",
  • "variables": {
    }
}

Response samples

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

Content type
application/json
{
  • "workerId": "aWorker",
  • "variables": {
    },
  • "localVariables": {
    }
}

Response samples

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

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

Content type
application/json
{
  • "workerId": "anId",
  • "newDuration": 100000
}

Response samples

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

Content type
application/json
{
  • "workerId": "aWorker",
  • "errorMessage": "Does not compute",
  • "retries": 3,
  • "retryTimeout": 60000
}

Response samples

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

Content type
application/json
{
  • "workerId": "anId",
  • "lockDuration": 100000
}

Response samples

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

Content type
application/json
{
  • "priority": 5
}

Response samples

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

Content type
application/json
{
  • "retries": 123
}

Response samples

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

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

Content type
application/json
Example

GET /filter?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

Responses

Response samples

Content type
application/json

OPTIONS /filter

{}

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

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

Content type
application/json

POST /filter/create

{
  • "resourceType": "Task",
  • "name": "Accounting Tasks",
  • "owner": "jonny1",
  • "query": {
    },
  • "properties": {
    }
}

Response samples

Content type
application/json

POST /filter/create

{
  • "id": "aFilterId",
  • "resourceType": "Task",
  • "name": "Accounting Tasks",
  • "owner": "jonny1",
  • "query": {
    },
  • "properties": {
    }
}

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

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

Content type
application/json
Example

GET /filter/aFilterId

{
  • "id": "9917d731-3cde-11e4-b704-f0def1e59da8",
  • "name": "Accounting Tasks",
  • "owner": null,
  • "properties": {
    },
  • "query": {
    },
  • "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

Content type
application/json

OPTIONS /filter/aFilterId

{}

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

Content type
application/json

PUT /filter/aFilterID

{
  • "resourceType": "Task",
  • "name": "My Tasks",
  • "owner": "jonny1",
  • "query": {
    },
  • "properties": {
    }
}

Response samples

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

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

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

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

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.

[
  • {
    },
  • {
    }
]

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

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

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.

[
  • {
    }
]

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

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

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

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

Content type
application/json

GET /group?name=Sales

[
  • {
    }
]

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

Content type
application/json

OPTIONS /group

{}

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

Content type
application/json
{
  • "name": "Sales"
}

Response samples

Content type
application/json

POST /group

[
  • {
    }
]

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

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

Content type
application/json
{
  • "name": "Sales"
}

Response samples

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

Content type
application/json
{
  • "id": "sales",
  • "name": "Sales",
  • "type": "Organizational Unit"
}

Response samples

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

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

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

Content type
application/json

OPTIONS /group/aGroupId

{}

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

Content type
application/json
{
  • "id": "sales",
  • "name": "Sales",
  • "type": "Organizational Unit"
}

Response samples

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

Content type
application/json

OPTIONS /group/sales/members

{}

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

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

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

Content type
application/json

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

[
  • {
    }
]

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

Content type
application/json
{
  • "activityType": "userTask",
  • "taskAssignee": "peter",
  • "sorting": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

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

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

Content type
application/json
{
  • "activityType": "userTask"
}

Response samples

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

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

Content type
application/json

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

[
  • {
    }
]

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

Content type
application/json

GET /history/batch/cleanable-batch-report

                                  An array containing finished batches information relevant to history cleanup.
[
  • {
    },
  • {
    }
]

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
query Parameters
sortBy
string

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

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

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

Content type
application/json
{
  • "absoluteRemovalTime": "2019-05-05T11:56:24.725+0200",
  • "historicBatchQuery": {
    },
  • "historicBatchIds": [
    ]
}

Response samples

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

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

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

Response samples

Content type
application/json

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

[
  • {
    },
  • {
    }
]

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

Response samples

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

Content type
application/json

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

[
  • {
    }
]

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

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

Content type
application/json

POST /history/decision-instance/delete

{
  • "historicDecisionInstanceIds": [
    ],
  • "historicDecisionInstanceQuery": {
    },
  • "deleteReason": "a delete reason"
}

Response samples

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

Content type
application/json

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

{
  • "absoluteRemovalTime": "2019-05-05T11:56:24.725+0200",
  • "hierarchical": true,
  • "historicDecisionInstanceQuery": {
    },
  • "historicDecisionInstanceIds": [
    ]
}

Response samples

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

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": [
    ],
  • "outputs": [
    ],
  • "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

Content type
application/json
Example

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

[
  • {
    }
]

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.

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

Content type
application/json

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

[
  • {
    },
  • {
    }
]

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.

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

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

Response samples

Content type
application/json

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

[
  • {
    },
  • {
    }
]

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.

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

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

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

Content type
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

Content type
application/json

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

[
  • {
    }
]

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

Content type
application/json
{
  • "externalTaskId": "anExternalTaskId"
}

Response samples

Content type
application/json

POST /history/external-task-log

[
  • {
    }
]

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

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

Content type
application/json
{
  • "externalTaskId": "anExternalTaskId"
}

Response samples

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

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

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

Responses

Response samples

Content type
application/json

GET /history/incident?processInstanceId=aProcInstId

[
  • {
    },
  • {
    }
]

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.

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.

Responses

Response samples

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

Content type
application/json

GET /history/job-log?jobId=aJobId

[
  • {
    }
]

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

Content type
application/json
{
  • "jobId": "aJobId"
}

Response samples

Content type
application/json

POST /history/job-log

[
  • {
    }
]

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

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

Content type
application/json
{
  • "jobId": "aJobId"
}

Response samples

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

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",
  • "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

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

Content type
application/json

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

[
  • {
    },
  • {
    }
]

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

Response samples

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

Content type
application/json
Example

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

[
  • {
    },
  • {
    }
]

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.

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.

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

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

[
  • {
    }
]

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.

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.

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

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": [
    ],
  • "sorting": [
    ]
}

Response samples

Content type
application/json

Response for POST /history/process-instance

[
  • {
    }
]

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.

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.

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

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.

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.

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

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

Response samples

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

Content type
application/json
{
  • "deleteReason": "aReason",
  • "historicProcessInstanceIds": [
    ],
  • "historicProcessInstanceQuery": {
    }
}

Response samples

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

Content type
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

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

Content type
application/json
Example
{
  • "absoluteRemovalTime": "2019-05-05T11:56:24.725+0200",
  • "hierarchical": true,
  • "historicProcessInstanceQuery": {
    },
  • "historicProcessInstanceIds": [
    ]
}

Response samples

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

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

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

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

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.

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

Content type
application/json

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

[
  • {
    }
]

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.

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

Content type
application/json
{
  • "taskVariables": [
    ],
  • "priority": 10,
  • "sorting": [
    ]
}

Response samples

Content type
application/json

POST /history/task

[
  • {
    }
]

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.

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

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.

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

Content type
application/json
{
  • "taskVariables": [
    ],
  • "priority": 10
}

Response samples

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

Content type
application/json
Example

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

[
  • {
    },
  • {
    }
]

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

Content type
application/json
Example

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

[
  • {
    }
]

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

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

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

Content type
application/json
{
  • "annotation": "Instances restarted due to wrong turn"
}

Response samples

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

Content type
application/json

GET /history/variable-instance?variableName=my_variable

[
  • {
    }
]

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

Content type
application/json
{
  • "variableName": "someVariable",
  • "variableValue": 42,
  • "sorting": [
    ]
}

Response samples

Content type
application/json

POST /history/variable-instance

[
  • {
    }
]

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

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

Content type
application/json
{
  • "variableName": "someVariable",
  • "variableValue": 42
}

Response samples

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

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

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

Content type

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

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

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

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

Content type
application/json

GET /history/cleanup/jobs

[
  • {
    },
  • {
    }
]

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

Content type
application/json

GET /identity/groups?userId=aUserId

{
  • "groups": [
    ],
  • "groupUsers": [
    ]
}

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

Content type
application/json

GET /identity/password-policy

{
  • "rules": [
    ]
}

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

Content type
application/json
{
  • "password": "myPassword",
  • "profile": {
    }
}

Response samples

Content type
application/json

POST /identity/password-policy

{
  • "rules": [
    ],
  • "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

Content type
application/json
{
  • "username": "testUser",
  • "password": "testPassword"
}

Response samples

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

Content type
application/json
[
  • {
    },
  • {
    }
]

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

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

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

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

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

Content type
application/json
{
  • "annotation": "my annotation"
}

Response samples

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

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

[
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "dueDates": [
    ],
  • "createTimes": [
    ],
  • "sorting": [
    ]
}

Response samples

Content type
application/json

POST /job

[
  • {
    },
  • {
    }
]

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

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

Content type
application/json
{
  • "dueDates": [
    ],
  • "createTimes": [
    ]
}

Response samples

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

Content type
application/json
{
  • "retries": 5,
  • "dueDate": "2017-04-06T13:57:45.000+0200",
  • "jobIds": [
    ],
  • "jobQuery": {
    }
}

Response samples

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

Content type
application/json
Example
{
  • "jobDefinitionId": "aJobDefinitionId",
  • "suspended": true
}

Response samples

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

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

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

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

Content type
application/json
{
  • "duedate": "2013-08-13T18:43:28.000+0200",
  • "cascade": false
}

Response samples

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

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

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

Content type
application/json
{
  • "priority": 10
}

Response samples

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

Content type
application/json
{
  • "retries": 3,
  • "dueDate": "2017-04-06T13:57:45.000+0200"
}

Response samples

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

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

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

Content type
application/json

GET /job-definition?activityIdIn=ServiceTask1,ServiceTask2

[
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "activityIdIn": [
    ],
  • "sorting": [
    ]
}

Response samples

Content type
application/json

POST /job-definition

[
  • {
    },
  • {
    }
]

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

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

Content type
application/json
{
  • "activityIdIn": [
    ]
}

Response samples

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

Content type
application/json
Example

PUT /job-definition/suspended

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

Response samples

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

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

Content type
application/json
{
  • "priority": 10,
  • "includeJobs": true
}

Response samples

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

Content type
application/json
{
  • "retries": 3,
  • "dueDate": "2017-04-06T13:57:45.000+0200"
}

Response samples

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

Content type
application/json
{
  • "suspended": true,
  • "includeJobs": true,
  • "executionDate": "2013-11-21T10:49:45.000+0200"
}

Response samples

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

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

Content type
application/json
Example

Correlate without result

{
  • "messageName": "aMessage",
  • "businessKey": "aBusinessKey",
  • "correlationKeys": {
    },
  • "processVariables": {
    }
}

Response samples

Content type
application/json
Example

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

[
  • {
    }
]

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

Content type
application/json
[
  • {
    }
]

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

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

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

Content type
application/json
{
  • "migrationPlan": {
    },
  • "processInstanceIds": [
    ],
  • "processInstanceQuery": {
    },
  • "skipCustomListeners": true
}

Response samples

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

Content type
application/json
{
  • "migrationPlan": {
    },
  • "processInstanceIds": [
    ],
  • "processInstanceQuery": {
    },
  • "skipCustomListeners": true
}

Response samples

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

Content type
application/json
{
  • "sourceProcessDefinitionId": "aProcessDefinitionId1",
  • "targetProcessDefinitionId": "aProcessDefinitionId2",
  • "updateEventTriggers": true,
  • "variables": {
    }
}

Response samples

Content type
application/json

POST /migration/generate

{
  • "sourceProcessDefinitionId": "aProcessDefinitionId1",
  • "targetProcessDefinitionId": "aProcessDefinitionId2",
  • "instructions": [
    ],
  • "variables": {
    }
}

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

Content type
application/json
{
  • "sourceProcessDefinitionId": "aProcessDefinitionId1",
  • "targetProcessDefinitionId": "aProcessDefinitionId2",
  • "instructions": [
    ],
  • "variables": {
    }
}

Response samples

Content type
application/json

POST /migration/validate

{
  • "instructionReports": [
    ],
  • "variableReports": {
    }
}

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

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

Content type
application/json
{
  • "processDefinitionId": "aProcessDefinitionId",
  • "instructions": [
    ],
  • "processInstanceIds": [
    ],
  • "processInstanceQuery": {
    },
  • "skipCustomListeners": true,
  • "annotation": "Modified to resolve an error."
}

Response samples

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

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

Content type
application/json
{
  • "processDefinitionId": "aProcessDefinitionId",
  • "instructions": [
    ],
  • "processInstanceIds": [
    ],
  • "processInstanceQuery": {
    },
  • "skipCustomListeners": true,
  • "annotation": "Modified to resolve an error."
}

Response samples

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

Content type
application/json

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

[
  • {
    },
  • {
    }
]

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

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

Content type
application/json
{
  • "userId": "string",
  • "missingAuthorizations": [
    ],
  • "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

Content type
application/json

Response of GET /process-definition/key/invoice

{
  • "id": "invoice:1:c3a63aaa-2046-11e7-8f94-34f39ab71d4e",
  • "key": "invoice",
  • "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

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

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

Content type
application/json

GET /process-definition/anId/form-variables

{
  • "amount": {
    },
  • "firstName": {
    }
}

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

Content type
application/json
{
  • "historyTimeToLive": 5
}

Response samples

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

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

Content type
application/json
Example
{
  • "variables": {
    },
  • "businessKey": "myBusinessKey"
}

Response samples

Content type
application/json
Example

Response for starting a process instance at its default initial activity

{}

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

Content type
application/json

GET process-definition/key/aKey/startForm

{}

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

Content type
application/json
Example

Request with Query Parameter failedJobs=true

[
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "variables": {
    },
  • "businessKey": "myBusinessKey"
}

Response samples

Content type
application/json

POST /process-definition/key/aProcessDefinitionKey/submit-form

{}

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

Content type
application/json
{
  • "suspended": true,
  • "includeProcessInstances": true,
  • "executionDate": "2013-11-21T10:49:45T14:42:45"
}

Response samples

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

Content type
application/json
{
  • "userId": "string",
  • "missingAuthorizations": [
    ],
  • "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

Content type
application/json

Response of GET /process-definition/key/invoice/tenant-id/tenantOne

{
  • "id": "invoice:1:c3a63aaa-2046-11e7-8f94-34f39ab71d4e",
  • "key": "invoice",
  • "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

Response samples

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

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

Response samples

Content type
application/json

GET /process-definition/anId/form-variables

{
  • "amount": {
    },
  • "firstName": {
    }
}

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

Request samples

Content type
application/json
{
  • "historyTimeToLive": 5
}

Response samples

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

Response samples

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

Content type
application/json
Example
{
  • "variables": {
    },
  • "businessKey": "myBusinessKey"
}

Response samples

Content type
application/json
Example

Response for starting a process instance at its default initial activity

{}

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

Content type
application/json

GET process-definition/key/aKey/tenant-id/aTenantId/startForm

{}

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

Response samples

Content type
application/json
Example

Request with Query Parameter failedJobs=true

[
  • {
    },
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "variables": {
    },
  • "businessKey": "myBusinessKey"
}

Response samples

Content type
application/json

POST /process-definition/key/aProcessDefinitionKey/tenant-id/aTenantId/submit-form

{}

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

Content type
application/json
{
  • "suspended": true,
  • "includeProcessInstances": true,
  • "executionDate": "2013-11-21T10:49:45T14:42:45"
}

Response samples

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

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

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

Content type
application/json
Example

Request with Query Parameter failedJobs=true

[
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "processDefinitionKey": "aProcessDefinitionKey",
  • "suspended": true,
  • "includeProcessInstances": true,
  • "executionDate": "2013-11-21T10:49:45T14:42:45"
}

Response samples

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

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

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",
  • "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

Content type

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

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

Content type
application/json

GET /process-definition/anId/form-variables

{
  • "amount": {
    },
  • "firstName": {
    }
}

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

Content type
application/json
{
  • "historyTimeToLive": 5
}

Response samples

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

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

Content type
application/json
Example
{
  • "instructions": [
    ],
  • "processInstanceIds": [
    ],
  • "initialVariables": true,
  • "skipCustomListeners": true,
  • "withoutBusinessKey": true
}

Response samples

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

Content type
application/json
Example
{
  • "instructions": [
    ],
  • "processInstanceIds": [
    ],
  • "initialVariables": true,
  • "skipCustomListeners": true,
  • "withoutBusinessKey": true
}

Response samples

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

Content type
application/json
Example
{
  • "variables": {
    },
  • "businessKey": "myBusinessKey"
}

Response samples

Content type
application/json
Example

Response for starting a process instance at its default initial activity

{}

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

Content type
application/json

GET process-definition/anId/startForm

{}

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

Content type
application/json

GET /process-definition/aProcessDefinitionId/static-called-process-definitions

[
  • {
    },
  • {
    }
]

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

Content type
application/json
Example

Request with Query Parameter failedJobs=true

[
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "variables": {
    },
  • "businessKey": "myBusinessKey"
}

Response samples

Content type
application/json

POST /process-definition/aProcessDefinitionId/submit-form

{}

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

Content type
application/json
{
  • "suspended": true,
  • "includeProcessInstances": true,
  • "executionDate": "2013-11-21T10:49:45T14:42:45"
}

Response samples

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

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

Content type
application/json

Response for GET /process-instance?variables=myVariable_eq_camunda,mySecondVariable_neq_aBadValue

[
  • {
    }
]

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

Content type
application/json
{
  • "variables": [
    ],
  • "processDefinitionId": "aProcessDefinitionId",
  • "sorting": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

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

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

Content type
application/json
{
  • "variables": [
    ],
  • "processDefinitionId": "aProcessDefinitionId"
}

Response samples

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.

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

Content type
application/json
{
  • "deleteReason": "aReason",
  • "processInstanceIds": [
    ],
  • "skipCustomListeners": true,
  • "skipSubprocesses": true
}

Response samples

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.

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

Content type
application/json
{
  • "deleteReason": "aReason",
  • "historicProcessInstanceQuery": {
    },
  • "skipCustomListeners": true,
  • "skipSubprocesses": true
}

Response samples

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

Content type
application/json
{
  • "retries": 5,
  • "dueDate": "2017-04-06T13:57:45.000+0200",
  • "processInstances": [
    ],
  • "processInstanceQuery": {
    }
}

Response samples

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

Content type
application/json
{
  • "retries": 5,
  • "dueDate": "2017-04-06T13:57:45.000+0200",
  • "historicProcessInstanceQuery": {
    },
  • "processInstances": [
    ]
}

Response samples

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

Content type
application/json

Correlate a message to process instances in a batch

{
  • "messageName": "a-message-name",
  • "processInstanceIds": [
    ],
  • "processInstanceQuery": {
    },
  • "variables": {
    }
}

Response samples

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

Content type
application/json
Example

Suspend Process Instance By Process Definition Id

{
  • "processDefinitionId": "aProcDefId",
  • "suspended": true
}

Response samples

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

Content type
application/json

Suspend Process Instance In Batch

{
  • "processInstanceIds": [
    ],
  • "suspended": true
}

Response samples

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

Content type
application/json

Set variables to process instances in a batch

{
  • "processInstanceIds": [
    ],
  • "processInstanceQuery": {
    },
  • "variables": {
    }
}

Response samples

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

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

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

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": [
    ],
  • "childTransitionInstances": [ ],
  • "executionIds": [
    ],
  • "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

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "skipCustomListeners": true,
  • "skipIoMappings": true,
  • "instructions": [
    ],
  • "annotation": "Modified to resolve an error."
}

Response samples

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

Content type
application/json
{
  • "skipCustomListeners": true,
  • "skipIoMappings": true,
  • "instructions": [
    ],
  • "annotation": "Modified to resolve an error."
}

Response samples

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

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

Content type
application/json
Example
{
  • "aVariableKey": {
    }
}

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

Content type
application/json

Status 204 Response: No content.

{
  • "modifications": {
    },
  • "deletions": [
    ]
}

Response samples

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

Content type
application/json
Example
{
  • "value": {
    },
  • "type": "Object",
  • "valueInfo": {
    }
}

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

Content type
application/json
Example

Status 204. No content.

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

Response samples

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

Content type
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

Content type
multipart/form-data
Example

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

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

Content type
application/json

The content of the Request Body

{
  • "name": "policy_conditions_changed",
  • "variables": {
    }
}

Response samples

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

Content type
application/json

The Response content of a status 200

[
  • {
    },
  • {
    }
]

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

Content type
application/json

The content of the Request Body

{
  • "version": "7.11.0",
  • "sortBy": "timestamp",
  • "sortOrder": "asc"
}

Response samples

Content type
application/json

The Response content of a status 200

[
  • {
    }
]

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.

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.

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

Content type
application/json

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

[
  • {
    }
]

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.

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

Content type
application/json
Example
{
  • "taskVariables": [
    ],
  • "processInstanceBusinessKeyIn": "aBusinessKey,anotherBusinessKey",
  • "assigneeIn": "anAssignee,anotherAssignee",
  • "priority": 10,
  • "sorting": [
    ]
}

Response samples

Content type
application/json
Example
[
  • {
    }
]

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.

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.

Responses

Response samples

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.

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

Content type
application/json
Example
{
  • "taskVariables": [
    ],
  • "processInstanceBusinessKeyIn": "aBusinessKey,anotherBusinessKey",
  • "assigneeIn": "anAssignee,anotherAssignee",
  • "priority": 10,
  • "sorting": [
    ]
}

Response samples

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

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

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

Content type
[
  • {
    },
  • {
    },
  • {
    }
]

Delete

Removes a task by id.

Authorizations:
basicAuth
path Parameters
id
required
string

The id of the task to be removed.

Responses

Response samples

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

Content type
application/json
{
  • "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": {
    },
  • "tenantId": "aTenantId"
}

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

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

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

Content type
application/json

POST /task/anId/assignee

{
  • "userId": "aUserId"
}

Response samples

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

Content type
application/json

POST /task/aTaskId/bpmnError

{
  • "errorCode": "bpmn-error-543",
  • "errorMessage": "anErrorMessage",
  • "variables": {
    }
}

Response samples

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

Content type
application/json

POST /task/aTaskId/bpmnEscalation

{
  • "escalationCode": "bpmn-escalation-432",
  • "variables": {
    }
}

Response samples

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

Content type
application/json

POST /task/anId/claim

{
  • "userId": "aUserId"
}

Response samples

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

Content type
application/json
Example

Complete Task with variables in return

{
  • "variables": {
    },
  • "withVariablesInReturn": true
}

Response samples

Content type
application/json

Response Body

{
  • "aVariable": {
    },
  • "anotherVariable": {
    },
  • "aThirdVariable": {
    }
}

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

Content type
application/json

POST /task/anId/delegate

{
  • "userId": "aUserId"
}

Response samples

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

Content type

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

Content type
application/json

GET /task/anId/form

{}

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

Content type
application/json

GET /task/anId/form-variables

{
  • "amount": {
    },
  • "firstName": {
    }
}

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

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

Content type
application/json

POST /task/anId/resolve

{
  • "variables": {
    }
}

Response samples

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

Content type
application/json
Example

POST /task/anId/submit-form

{
  • "variables": {
    }
}

Response samples

Content type
application/json

Response of a submitted task form with variables in return

{
  • "aVariable": {
    },
  • "anotherVariable": {
    },
  • "aThirdVariable": {
    }
}

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

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

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

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

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

Content type
application/json
{}

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

Content type
application/json
{
  • "userId": "string",
  • "missingAuthorizations": [
    ],
  • "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

Content type
application/json
{}

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

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

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "message": "a task comment",
  • "processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687"
}

Response samples

Content type
application/json
{
  • "links": [],
  • "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

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

Content type
application/json
Example
{
  • "aVariableKey": {
    }
}

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

Content type
application/json

Status 204 Response: No content.

{
  • "modifications": {
    },
  • "deletions": [
    ]
}

Response samples

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

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

Content type
application/json
Example
{
  • "value": {
    },
  • "type": "Object",
  • "valueInfo": {
    }
}

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

Content type
application/json
Example

Status 204. No content.

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

Response samples

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

Content type
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

Content type
multipart/form-data
Example

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

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

Content type
application/json
Example
{
  • "aVariableKey": {
    }
}

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

Content type
application/json

Status 204 Response: No content.

{
  • "modifications": {
    },
  • "deletions": [
    ]
}

Response samples

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

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

Content type
application/json
Example
{
  • "value": {
    },
  • "type": "Object",
  • "valueInfo": {
    }
}

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

Content type
application/json
Example

Status 204. No content.

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

Response samples

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

Content type
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

Content type
multipart/form-data
Example

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

Content type
application/json
{
  • "type": "string",
  • "message": "string",
  • "code": 0
}

Telemetry

Fetch Telemetry Configuration

Fetches Telemetry Configuration.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json

The Response content of a status 200

{
  • "enableTelemetry": true
}

Configure Telemetry

Configures whether Camunda receives data collection of the process engine setup and usage.

Authorizations:
basicAuth
Request Body schema: application/json
enableTelemetry
boolean or null

Specifies if the telemetry data should be sent or not.

Responses

Request samples

Content type
application/json

The content of the Request Body

{
  • "enableTelemetry": true
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "message": "string",
  • "code": 0
}

Fetch Telemetry Data

Fetches Telemetry Data.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json

The Response content of a status 200

{
  • "installation": "8343cc7a-8ad1-42d4-97d2-43452c0bdfa3",
  • "product": {
    }
}

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

Content type
application/json

GET /tenant?name=tenantOne

[
  • {
    }
]

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

Content type
application/json

OPTIONS /tenant

{}

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

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

Content type
application/json
{
  • "id": "tenantOne",
  • "name": "Tenant One"
}

Response samples

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

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

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

Content type
application/json

OPTIONS /tenant/tenantOne

{}

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

Content type
application/json
{
  • "id": "tenantOne",
  • "name": "Tenant One"
}

Response samples

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

Content type
application/json

OPTIONS /tenant/tenantOne/group-members

{}

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

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

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

Content type
application/json

OPTIONS /tenant/tenantOne/user-members

{}

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

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

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

Content type
application/json
[
  • {
    },
  • {
    }
]

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

Content type
application/json
{}

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

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

Content type
application/json
{
  • "profile": {
    },
  • "credentials": {
    }
}

Delete

Deletes a user by id.

Authorizations:
basicAuth
path Parameters
id
required
string

The id of the user to be deleted.

Responses

Response samples

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

Content type
application/json
{}

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

Content type
application/json
{
  • "password": "s3cr3t",
  • "authenticatedUserPassword": "demo"
}

Response samples

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

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

Content type
application/json
{
  • "id": "jonny1",
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "aNewEmailAddress"
}

Response samples

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

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

Content type
application/json

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

[
  • {
    },
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "variableValues": [
    ],
  • "processInstanceIdIn": [
    ],
  • "sorting": [
    ]
}

Response samples

Content type
application/json

POST /variable-instance

[
  • {
    },
  • {
    },
  • {
    }
]

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.

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.

Responses

Response samples

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

Content type
application/json
{
  • "variableValues": [
    ],
  • "processInstanceIdIn": [
    ]
}

Response samples

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

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

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

Content type
application/json

The Response content of a status 200

{
  • "version": "7.13.0"
}