GET /bpm-engine/api/process-definitions

As of Version

product version 2021 Autumn | component version 

Request MethodGET
Response FormatJSON
Description

Retrieves a list of process definitions matching the conditions defined in various query parameters.

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

ParameterTypeDescription
categorystringOnly return process definitions with the given category.
categoryLikestring

Specify a string that has to match the category and that can contain % characters as placeholders for an arbitrary number of unknown characters.

categoryNotEqualsstringOnly return process definitions which do not have the given category.
keystringOnly return process definitions with the given key.
keyLikestringSpecify a string that has to match the key and that can contain % characters as placeholders for an arbitrary number of unknown characters.
latestbooleanOnly return the latest process definition versions. Can only be used together with key and keyLike parameters. Combination with any other parameters will result in an error with HTTP status code 400.
namestringOnly return process definitions with the given name.
nameLikestringSpecify a string that has to match the name and that can contain % characters as placeholders for an arbitrary number of unknown characters.
pageinteger($int32)Result page you want to retrieve (0…N). Default is 0 which means the first page.
sizeinteger($int32)Number of objects per page.
sortstringSorting of results either ascending (asc) or descending (desc). Default sort order is ascending.
startableByUserstringA valid user ID. Only return process definitions which user specified by the ID is authorized to start.
suspendedboolean

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

versionintegerOnly return process definitions with the given version.

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/process-definitions/?page=0&size=50&sort=desc&version=1
Response Example
{
  "objects": [
    {
      "id": "follow-up:1:00000000-0000-0000-0000-000000000000",
      "category": "examplecategory",
      "key": "follow-up",
      "name": "Follow-up",
      "description": "Follow up any document (NOTE: The start-form enforces 1 parameter (expiryDateTime) and 1 optional parameter (whatAbout))",
      "version": 1,
      "global": false,
      "startFormDefined": true,
      "suspended": false
    },
    {
      "id": "onesteptest_proc:1:00000000-0000-0000-0000-000000000001",
      "category": "exampleprocess",
      "key": "onesteptest_proc",
      "name": "One step test process",
      "description": null,
      "version": 1,
      "global": false,
      "startFormDefined": false,
      "suspended": false
    },
    {
      "id": "twosteptest_proc:1:00000000-0000-0000-0000-000000000002",
      "category": "exampleprocess",
      "key": "twosteptest_proc",
      "name": "Process-definition-name: Two step test process",
      "description": "This is description from model editor (high level, not the visual editor of process). The first step goes to initiator, second to no one (can be played with id-links). There is one form reference (get group id) in the first task.",
      "version": 1,
      "global": false,
      "startFormDefined": false,
      "suspended": false
    }
  ],
  "numItems": 3,
  "totalNumItems": 3,
  "hasMoreItems": false
}