Get Definitions

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.

Method

GET /process-definition

Parameters

Query Parameters

Name Description
processDefinitionId Filter by process definition id.
processDefinitionIdIn Filter by process definition ids.
name Filter by process definition name.
nameLike Filter by process definition names that the parameter is a substring of.
deploymentId Filter by the deployment the id belongs to.
deployedAfter 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.
deployedAt 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).
key Filter by process definition key, i.e., the id in the BPMN 2.0 XML. Exact match.
keysIn Filter by process definition keys.
keyLike Filter by process definition keys that the parameter is a substring of.
category Filter by process definition category. Exact match.
categoryLike Filter by process definition categories that the parameter is a substring of.
version Filter by process definition version.
latestVersion Only include those process definitions that are latest versions. Value may only be true, as false is the default behavior.
resourceName Filter by the name of the process definition resource. Exact match.
resourceNameLike Filter by names of those process definition resources that the parameter is a substring of.
startableBy Filter by a user name who is allowed to start the process.
active Only include active process definitions. Value may only be true, as false is the default behavior.
suspended Only include suspended process definitions. Value may only be true, as false is the default behavior.
incidentId Filter by the incident id.
incidentType Filter by the incident type. See the User Guide for a list of incident types.
incidentMessage Filter by the incident message. Exact match.
incidentMessageLike Filter by the incident message that the parameter is a substring of.
tenantIdIn Filter by a comma-separated list of tenant ids. A process definition must have one of the given tenant ids.
withoutTenantId Only include process definitions which belong to no tenant. Value may only be true, as false is the default behavior.
includeProcessDefinitionsWithoutTenantId 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 Filter by the version tag.
versionTagLike Filter by the version tag that the parameter is a substring of.
startableInTasklist Filter by process definitions which are startable in Tasklist.
notStartableInTasklist Filter by process definitions which are not startable in Tasklist.
startablePermissionCheck 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 Sort the results lexicographically by a given criterion. Valid values are category, key, id, name, version, deploymentId, deployTime, tenantId and versionTag. Must be used in conjunction with the sortOrder parameter. Note: Sorting by versionTag is string based. The version will not be interpreted. As an example, the sorting could return v0.1.0, v0.10.0, v0.2.0.
sortOrder Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Result

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

Name Value Description
id String The id of the process definition.
key String The key of the process definition, i.e., the id of the BPMN 2.0 XML process definition.
category String The category of the process definition.
description String The description of the process definition.
name String The name of the process definition.
version Number The version of the process definition that the engine assigned to it.
resource String The file name of the process definition.
deploymentId String The deployment id of the process definition.
diagram String The file name of the process definition diagram, if it exists.
suspended Boolean A flag indicating whether the definition is suspended or not.
tenantId String The tenant id of the process definition.
versionTag String The version tag of the process or null when no version tag is set
historyTimeToLive Number History time to live value of the process definition. Is used within History cleanup.
startableInTasklist Boolean A flag indicating whether the process definition is startable in Tasklist or not.

Response Codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

Example

Request

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

Response

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

On this Page: