GET /bpm-engine/api/processes

Owned by Technische Redaktion
Nov 12, 2021
2 min read
As of Version

product version 2021 Autumn | component version 

Request MethodGET
Response FormatJSON
Description

Retrieves a list of processes of the currently active user that are matching the conditions defined in various query parameters.

The following query parameters can optionally be added to the request URL.

ParameterTypeDescription
businessKeystringOnly return process instances with the given businessKey.
businessKeyLikestringSpecify a string that has to match the businessKey and that can contain % characters as placeholders for an arbitrary number of unknown characters.
excludeSubprocessesbooleanReturn only process instances which are not sub-processes.
includeProcessVariablesbooleanInclude process variables in the result.
involvedUserstringOnly return process instances in which the given user is involved.
namestringOnly return process instances with the given name.
nameLikestringOnly return process instances with a name like the given name.
nameLikeIgnoreCasestringOnly return process instances with a name like the given name ignoring case.
pageinteger($int32)Result page you want to retrieve (0…N). Default is 0 which means the first page.
processDefinitionCategorystringOnly return process instances with the given process definition category.
processDefinitionIdstringOnly return process instances with the given process definition ID.
processDefinitionKeystringOnly return process instances with the given process definition key.
processDefinitionVersionintegerOnly return process instances with the given process definition version.
sizeinteger($int32)Number of objects per page.
sortstringSorting of results either ascending (asc) or descending (desc). Default sort order is ascending.
startedAfterstringOnly return process instances started after the given date.
startedBeforestringOnly return process instances started before the given date.
startedBystringOnly return process instances started by the given user.
subProcessInstanceIdstringOnly return process instances which have the given sub-process instance ID (for processes started as a call activity).
superProcessInstanceIdstringOnly return process instances which have the given super process instance ID (for processes that have a call activity).
suspendedboolean

If true, only suspended processes are returned. If false, only active processes (which are not suspended) are returned.

isCompletedbooleanIf true, only completed processes are returned. If false, only running processes are returned. If not specified, both completed und running processes are returned.

Meaning of HTTP status codes:

HTTP Status CodeDescription
200Request was successful and the process definitions are returned.
400A parameter was passed in the wrong format or latest is used with parameters other than key and keyLike. The status message contains additional information.
401The calling user is not authorized.
Request HeaderContent-Type: application/json
Request Example
https://<host>/bpm-engine/api/processes?page=0&size=1
Response Example
{
  "objects": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "testProcessInstanceName",
      "businessKey": "testBusinessKey",
      "processDefinitionId": "twosteptest_proc:4:8dc694a2-10b1-11ec-99ef-027ea5eeae02",
      "processDefinitionName": "Two tasks test process",
      "processDefinitionDescription": "Process shall be started with Web-API Gateway variable subject to be shown in the same column of the inbox and with . Both tasks to initiator.",
      "startUserId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "startTime": "2021-11-01T12:28:46.363Z",
      "deleteReason": null,
      "endActivityId": null,
      "startActivityId": "startEvent1",
      "durationInMillis": null,
      "endTime": null,
      "suspended": false,
      "variables": []
    }
  ],
  "numItems": 1,
  "totalNumItems": 1,
  "hasMoreItems": false
}