Question

15.5.1. Get a process instance

GET runtime/process-instances/{processInstanceId}

Table 68. Get a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to get.

Table 69. Get a process instance - Response codes

Response code	Description
200	Indicates the process instance was found and returned.
404	Indicates the requested process instance was not found.

Success response body:

{
   "id":"7",
   "url":"http://localhost:8182/runtime/process-instances/7",
   "businessKey":"myBusinessKey",
   "suspended":false,
   "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
   "activityId":"processTask",
   "tenantId": null
}

15.5.2. Delete a process instance

DELETE runtime/process-instances/{processInstanceId}

Table 70. Delete a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to delete.

Table 71. Delete a process instance - Response codes

Response code	Description
204	Indicates the process instance was found and deleted. Response body is left empty intentionally.
404	Indicates the requested process instance was not found.

15.5.3. Activate or suspend a process instance

PUT runtime/process-instances/{processInstanceId}

Table 72. Activate or suspend a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to activate/suspend.

Request response body (suspend):

{
   "action":"suspend"
}

Request response body (activate):

{
   "action":"activate"
}

Table 73. Activate or suspend a process instance - Response codes

Response code	Description
200	Indicates the process instance was found and action was executed.
400	Indicates an invalid action was supplied.
404	Indicates the requested process instance was not found.
409	Indicates the requested process instance action cannot be executed since the process-instance is already activated/suspended.

15.5.4. Start a process instance

POST runtime/process-instances

Request body (start by process definition id):

{
   "processDefinitionId":"oneTaskProcess:1:158",
   "businessKey":"myBusinessKey",
   "returnVariables":true,
   "variables": [
    {
    "name":"myVar",
    "value":"This is a variable",
    }
   ]
}

Request body (start by process definition key):

{
   "processDefinitionKey":"oneTaskProcess",
   "businessKey":"myBusinessKey",
   "returnVariables":false,
   "tenantId": "tenant1",
   "variables": [
    {
    "name":"myVar",
    "value":"This is a variable",
    }
   ]
}

Request body (start by message):

{
   "message":"newOrderMessage",
   "businessKey":"myBusinessKey",
   "tenantId": "tenant1",
   "variables": [
    {
    "name":"myVar",
    "value":"This is a variable",
    }
   ]
}

Note that also a transientVariables property is accepted as part of this json, that follows the same structure as the variables property.

The returnVariables property can be used to get the existing variables in the process instance context back in the response. By default the variables are not returned.

Only one of processDefinitionId, processDefinitionKey or message can be used in the request body. Parameters businessKey, variables and tenantId are optional. If tenantId is omitted, the default tenant will be used. More information about the variable format can be found in the REST variables section. Note that the variable-scope that is supplied is ignored, process-variables are always local.

Table 74. Start a process instance - Response codes

Response code	Description
201	Indicates the process instance was created.
400	Indicates either the process-definition was not found (based on id or key), no process is started by sending the given message or an invalid variable has been passed. Status description contains additional information about the error.

Success response body:

{
   "id":"7",
   "url":"http://localhost:8182/runtime/process-instances/7",
   "businessKey":"myBusinessKey",
   "suspended":false,
   "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
   "activityId":"processTask",
   "tenantId" : null
}

15.5.5. List of process instances

GET runtime/process-instances

Table 75. List of process instances - URL query parameters

Parameter	Required	Value	Description
id	No	String	Only return process instance with the given id.
processDefinitionKey	No	String	Only return process instances with the given process definition key.
processDefinitionId	No	String	Only return process instances with the given process definition id.
businessKey	No	String	Only return process instances with the given businessKey.
involvedUser	No	String	Only return process instances in which the given user is involved.
suspended	No	Boolean	If true, only return process instance which are suspended. If false, only return process instances which are not suspended (active).
superProcessInstanceId	No	String	Only return process instances which have the given super process-instance id (for processes that have a call-activities).
subProcessInstanceId	No	String	Only return process instances which have the given sub process-instance id (for processes started as a call-activity).
excludeSubprocesses	No	Boolean	Return only process instances which aren’t sub processes.
includeProcessVariables	No	Boolean	Indication to include process variables in the result.
tenantId	No	String	Only return process instances with the given tenantId.
tenantIdLike	No	String	Only return process instances with a tenantId like the given value.
withoutTenantId	No	Boolean	If true, only returns process instances without a tenantId set. If false, the withoutTenantId parameter is ignored.
sort	No	String	Sort field, should be either one of id (default), processDefinitionId, tenantId or processDefinitionKey.

Table 76. List of process instances - Response codes

Response code	Description
200	Indicates request was successful and the process-instances are returned
400	Indicates a parameter was passed in the wrong format . The status-message contains additional information.

Success response body:

{
   "data":[
    {
     "id":"7",
     "url":"http://localhost:8182/runtime/process-instances/7",
     "businessKey":"myBusinessKey",
     "suspended":false,
     "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
     "activityId":"processTask",
     "tenantId" : null
    }


   ],
   "total":2,
   "start":0,
   "sort":"id",
   "order":"asc",
   "size":2
}

15.5.6. Query process instances

POST query/process-instances

Request body:

{
  "processDefinitionKey":"oneTaskProcess",
  "variables":
  [
  {
    "name" : "myVariable",
    "value" : 1234,
    "operation" : "equals",
    "type" : "long"
  }
  ]
}

The request body can contain all possible filters that can be used in the List process instances URL query. On top of these, it’s possible to provide an array of variables to include in the query, with their format described here.

The general paging and sorting query-parameters can be used for this URL.

Table 77. Query process instances - Response codes

Response code	Description
200	Indicates request was successful and the process-instances are returned
400	Indicates a parameter was passed in the wrong format . The status-message contains additional information.

Success response body:

{
   "data":[
    {
     "id":"7",
     "url":"http://localhost:8182/runtime/process-instances/7",
     "businessKey":"myBusinessKey",
     "suspended":false,
     "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
     "activityId":"processTask",
     "tenantId" : null
    }


   ],
   "total":2,
   "start":0,
   "sort":"id",
   "order":"asc",
   "size":2
}

15.5.7. Get diagram for a process instance

GET runtime/process-instances/{processInstanceId}/diagram

Table 78. Get diagram for a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to get the diagram for.

Table 79. Get diagram for a process instance - Response codes

Response code	Description
200	Indicates the process instance was found and the diagram was returned.
400	Indicates the requested process instance was not found but the process doesn’t contain any graphical information (BPMN:DI) and no diagram can be created.
404	Indicates the requested process instance was not found.

Success response body:

{
   "id":"7",
   "url":"http://localhost:8182/runtime/process-instances/7",
   "businessKey":"myBusinessKey",
   "suspended":false,
   "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
   "activityId":"processTask"
}

15.5.8. Get involved people for process instance

GET runtime/process-instances/{processInstanceId}/identitylinks

Table 80. Get involved people for process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to the links for.

Table 81. Get involved people for process instance - Response codes

Response code	Description
200	Indicates the process instance was found and links are returned.
404	Indicates the requested process instance was not found.

Success response body:

[
   {
    "url":"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType",
    "user":"john",
    "group":null,
    "type":"customType"
   },
   {
    "url":"http://localhost:8182/runtime/process-instances/5/identitylinks/users/paul/candidate",
    "user":"paul",
    "group":null,
    "type":"candidate"
   }
]

Note that the groupId will always be null, as it’s only possible to involve users with a process-instance.

15.5.9. Add an involved user to a process instance

POST runtime/process-instances/{processInstanceId}/identitylinks

Table 82. Add an involved user to a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to the links for.

Request body:

{
  "userId":"kermit",
  "type":"participant"
}

Both userId and type are required.

Table 83. Add an involved user to a process instance - Response codes

Response code	Description
201	Indicates the process instance was found and the link is created.
400	Indicates the requested body did not contain a userId or a type.
404	Indicates the requested process instance was not found.

Success response body:

{
   "url":"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType",
   "user":"john",
   "group":null,
   "type":"customType"
}

Note that the groupId will always be null, as it’s only possible to involve users with a process-instance.

15.5.10. Remove an involved user to from process instance

DELETE runtime/process-instances/{processInstanceId}/identitylinks/users/{userId}/{type}

Table 84. Remove an involved user to from process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance.
userId	Yes	String	The id of the user to delete link for.
type	Yes	String	Type of link to delete.

Table 85. Remove an involved user to from process instance - Response codes

Response code	Description
204	Indicates the process instance was found and the link has been deleted. Response body is left empty intentionally.
404	Indicates the requested process instance was not found or the link to delete doesn’t exist. The response status contains additional information about the error.

Success response body:

{
   "url":"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType",
   "user":"john",
   "group":null,
   "type":"customType"
}

Note that the groupId will always be null, as it’s only possible to involve users with a process-instance.

15.5.11. List of variables for a process instance

GET runtime/process-instances/{processInstanceId}/variables

Table 86. List of variables for a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to the variables for.

Table 87. List of variables for a process instance - Response codes

Response code	Description
200	Indicates the process instance was found and variables are returned.
404	Indicates the requested process instance was not found.

Success response body:

[
   {
    "name":"intProcVar",
    "type":"integer",
    "value":123,
    "scope":"local"
   },
   {
    "name":"byteArrayProcVar",
    "type":"binary",
    "value":null,
    "valueUrl":"http://localhost:8182/runtime/process-instances/5/variables/byteArrayProcVar/data",
    "scope":"local"
   }
]

In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response. Note that only local scoped variables are returned, as there is no global scope for process-instance variables.

15.5.12. Get a variable for a process instance

GET runtime/process-instances/{processInstanceId}/variables/{variableName}

Table 88. Get a variable for a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to the variables for.
variableName	Yes	String	Name of the variable to get.

Table 89. Get a variable for a process instance - Response codes

Response code	Description
200	Indicates both the process instance and variable were found and variable is returned.
400	Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.
404	Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.

Success response body:

   {
    "name":"intProcVar",
    "type":"integer",
    "value":123,
    "scope":"local"
   }

In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response. Note that only local scoped variables are returned, as there is no global scope for process-instance variables.

15.5.13. Create (or update) variables on a process instance

POST runtime/process-instances/{processInstanceId}/variables

PUT runtime/process-instances/{processInstanceId}/variables

When using POST, all variables that are passed are created. In case one of the variables already exists on the process instance, the request results in an error (409 - CONFLICT). When PUT is used, nonexistent variables are created on the process-instance and existing ones are overridden without any error.

Table 90. Create (or update) variables on a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to the variables for.

Request body:

[
   {
    "name":"intProcVar"
    "type":"integer"
    "value":123
   },

   ...
]

Any number of variables can be passed into the request body array. More information about the variable format can be found in the REST variables section. Note that scope is ignored, only local variables can be set in a process instance.

Table 91. Create (or update) variables on a process instance - Response codes

Response code	Description
201	Indicates the process instance was found and variable is created.
400	Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.
404	Indicates the requested process instance was not found.
409	Indicates the process instance was found but already contains a variable with the given name (only thrown when POST method is used). Use the update-method instead.

Success response body:

[
   {
    "name":"intProcVar",
    "type":"integer",
    "value":123,
    "scope":"local"
   },

   ...

]

15.5.14. Update a single variable on a process instance

PUT runtime/process-instances/{processInstanceId}/variables/{variableName}

Table 92. Update a single variable on a process instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to the variables for.
variableName	Yes	String	Name of the variable to get.

Request body:

 {
  "name":"intProcVar"
  "type":"integer"
  "value":123
 }

More information about the variable format can be found in the REST variables section. Note that scope is ignored, only local variables can be set in a process instance.

Table 93. Update a single variable on a process instance - Response codes

Response code	Description
200	Indicates both the process instance and variable were found and variable is updated.
404	Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.

Success response body:

{
  "name":"intProcVar",
  "type":"integer",
  "value":123,
  "scope":"local"
}

In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it’s a plain variable, the value is present in the response. Note that only local scoped variables are returned, as there is no global scope for process-instance variables.

15.5.15. Create a new binary variable on a process-instance

POST runtime/process-instances/{processInstanceId}/variables

Table 94. Create a new binary variable on a process-instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to create the new variable for.

Request body:

The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

• name: Required name of the variable.

• type: Type of variable that is created. If omitted, binary is assumed and the binary data in the request will be stored as an array of bytes.

Success response body:

{
  "name" : "binaryVariable",
  "scope" : "local",
  "type" : "binary",
  "value" : null,
  "valueUrl" : "http://.../runtime/process-instances/123/variables/binaryVariable/data"
}

Table 95. Create a new binary variable on a process-instance - Response codes

Response code	Description
201	Indicates the variable was created and the result is returned.
400	Indicates the name of the variable to create was missing. Status message provides additional information.
404	Indicates the requested process instance was not found.
409	Indicates the process instance already has a variable with the given name. Use the PUT method to update the task variable instead.
415	Indicates the serializable data contains an object for which no class is present in the JVM running the Flowable engine and therefore cannot be deserialized.

15.5.16. Update an existing binary variable on a process-instance

PUT runtime/process-instances/{processInstanceId}/variables

Table 96. Update an existing binary variable on a process-instance - URL parameters

Parameter	Required	Value	Description
processInstanceId	Yes	String	The id of the process instance to create the new variable for.

Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

• name: Required name of the variable.

• type: Type of variable that is created. If omitted, binary is assumed and the binary data in the request will be stored as an array of bytes.

Success response body:

{
  "name" : "binaryVariable",
  "scope" : "local",
  "type" : "binary",
  "value" : null,
  "valueUrl" : "http://.../runtime/process-instances/123/variables/binaryVariable/data"
}

Table 97. Update an existing binary variable on a process-instance - Response codes

Response code	Description
200	Indicates the variable was updated and the result is returned.
400	Indicates the name of the variable to update was missing. Status message provides additional information.
404	Indicates the requested process instance was not found or the process instance does not have a variable with the given name.
415	Indicates the serializable data contains an object for which no class is present in the JVM running the Flowable engine and therefore cannot be deserialized.