GET /bpm-engine/api/processes

As of Version

product version 2021 Autumn | component version

Request Method GET

Response Format JSON

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.

Parameter	Type	Description
`businessKey`	string	Only return process instances with the given `businessKey`.
`businessKeyLike`	string	Specify a string that has to match the `businessKey` and that can contain `%` characters as placeholders for an arbitrary number of unknown characters.
`excludeSubprocesses`	boolean	Return only process instances which are not sub-processes.
`includeProcessVariables`	boolean	Include process variables in the result.
`involvedUser`	string	Only return process instances in which the given user is involved.
`name`	string	Only return process instances with the given name.
`nameLike`	string	Only return process instances with a name like the given name.
`nameLikeIgnoreCase`	string	Only return process instances with a name like the given name ignoring case.
`page`	integer($int32)	Result page you want to retrieve (0…N). Default is `0` which means the first page.
`processDefinitionCategory`	string	Only return process instances with the given process definition category.
`processDefinitionId`	string	Only return process instances with the given process definition ID.
`processDefinitionKey`	string	Only return process instances with the given process definition key.
`processDefinitionVersion`	integer	Only return process instances with the given process definition version.
`size`	integer($int32)	Number of objects per page.
`sort`	string	Sorting of results either ascending (`asc`) or descending (`desc`). Default sort order is ascending.
`startedAfter`	string	Only return process instances started after the given date.
`startedBefore`	string	Only return process instances started before the given date.
`startedBy`	string	Only return process instances started by the given user specified by `userId`. The result depends on the permissions of the currently logged-in user: If `startedBy` is not specified and the user has admin access, all processes are returned. the user has no admin access, user gets only the own processes. If `startedBy` is specified and the user has admin access, all processes started by the specified user are returned. the user has no admin access, only the own `userId` is allowed as value for `startedBy`. A request with a different `userId` as value for `startedBy` returns an error.
`subProcessInstanceId`	string	Only return process instances which have the given sub-process instance ID (for processes started as a call activity).
`superProcessInstanceId`	string	Only return process instances which have the given super process instance ID (for processes that have a call activity).
`suspended`	boolean	If `true`, only suspended processes are returned. If `false`, only active processes (which are not suspended) are returned.
`isCompleted`	boolean	If `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 Code	Description
200	Request was successful and the process definitions are returned.
400	A parameter was passed in the wrong format or `latest` is used with parameters other than `key` and `keyLike`. The status message contains additional information.
401	The calling user is not authorized.

Request Header Content-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
}