Question

15.6.1. Get an execution

GET runtime/executions/{executionId}

Table 98. Get an execution - URL parameters

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution to get.

Table 99. Get an execution - Response codes

Response code	Description
200	Indicates the execution was found and returned.
404	Indicates the execution was not found.

Success response body:

{
   "id":"5",
   "url":"http://localhost:8182/runtime/executions/5",
   "parentId":null,
   "parentUrl":null,
   "processInstanceId":"5",
   "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
   "suspended":false,
   "activityId":null,
   "tenantId": null
}

15.6.2. Execute an action on an execution

PUT runtime/executions/{executionId}

Table 100. Execute an action on an execution - URL parameters

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution to execute action on.

Request body (signal an execution):

{
  "action":"signal"
}

Both a variables and transientVariables property is accepted with following structure:

{
  "action":"signal",
  "variables" : [
  {
    "name": "myVar",
    "value": "someValue"
  }
  ]
}

Request body (signal event received for execution):

{
  "action":"signalEventReceived",
  "signalName":"mySignal"
  "variables": [  ]
}

Notifies the execution that a signal event has been received, requires a signalName parameter. Optional variables can be passed that are set on the execution before the action is executed.

Request body (signal event received for execution):

{
  "action":"messageEventReceived",
  "messageName":"myMessage"
  "variables": [  ]
}

Notifies the execution that a message event has been received, requires a messageName parameter. Optional variables can be passed that are set on the execution before the action is executed.

Table 101. Execute an action on an execution - Response codes

Response code	Description
200	Indicates the execution was found and the action is performed.
204	Indicates the execution was found, the action was performed and the action caused the execution to end.
400	Indicates an illegal action was requested, required parameters are missing in the request body or illegal variables are passed in. Status description contains additional information about the error.
404	Indicates the execution was not found.

Success response body (in case execution is not ended due to action):

{
   "id":"5",
   "url":"http://localhost:8182/runtime/executions/5",
   "parentId":null,
   "parentUrl":null,
   "processInstanceId":"5",
   "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
   "suspended":false,
   "activityId":null,
   "tenantId" : null
}

15.6.3. Get active activities in an execution

GET runtime/executions/{executionId}/activities

Returns all activities which are active in the execution and in all child-executions (and their children, recursively), if any.

Table 102. Get active activities in an execution - URL parameters

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution to get activities for.

Table 103. Get active activities in an execution - Response codes

Response code	Description
200	Indicates the execution was found and activities are returned.
404	Indicates the execution was not found.

Success response body:

[
  "userTaskForManager",
  "receiveTask"
]

15.6.4. List of executions

GET runtime/executions

Table 104. List of executions - URL query parameters

Parameter	Required	Value	Description
id	No	String	Only return executions with the given id.
activityId	No	String	Only return executions with the given activity id.
processDefinitionKey	No	String	Only return executions with the given process definition key.
processDefinitionId	No	String	Only return executions with the given process definition id.
processInstanceId	No	String	Only return executions which are part of the process instance with the given id.
messageEventSubscriptionName	No	String	Only return executions which are subscribed to a message with the given name.
signalEventSubscriptionName	No	String	Only return executions which are subscribed to a signal with the given name.
parentId	No	String	Only return executions which are a direct child of the given execution.
tenantId	No	String	Only return executions with the given tenantId.
tenantIdLike	No	String	Only return executions with a tenantId like the given value.
withoutTenantId	No	Boolean	If true, only returns executions without a tenantId set. If false, the withoutTenantId parameter is ignored.
sort	No	String	Sort field, should be either one of processInstanceId (default), processDefinitionId, processDefinitionKey or tenantId.

Table 105. List of executions - Response codes

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

Success response body:

{
   "data":[
    {
     "id":"5",
     "url":"http://localhost:8182/runtime/executions/5",
     "parentId":null,
     "parentUrl":null,
     "processInstanceId":"5",
     "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
     "suspended":false,
     "activityId":null,
     "tenantId":null
    },
    {
     "id":"7",
     "url":"http://localhost:8182/runtime/executions/7",
     "parentId":"5",
     "parentUrl":"http://localhost:8182/runtime/executions/5",
     "processInstanceId":"5",
     "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
     "suspended":false,
     "activityId":"processTask",
     "tenantId":null
    }
   ],
   "total":2,
   "start":0,
   "sort":"processInstanceId",
   "order":"asc",
   "size":2
}

15.6.5. Query executions

POST query/executions

Request body:

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

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

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

Table 106. Query executions - Response codes

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

Success response body:

{
   "data":[
    {
     "id":"5",
     "url":"http://localhost:8182/runtime/executions/5",
     "parentId":null,
     "parentUrl":null,
     "processInstanceId":"5",
     "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
     "suspended":false,
     "activityId":null,
     "tenantId":null
    },
    {
     "id":"7",
     "url":"http://localhost:8182/runtime/executions/7",
     "parentId":"5",
     "parentUrl":"http://localhost:8182/runtime/executions/5",
     "processInstanceId":"5",
     "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
     "suspended":false,
     "activityId":"processTask",
     "tenantId":null
    }
   ],
   "total":2,
   "start":0,
   "sort":"processInstanceId",
   "order":"asc",
   "size":2
}

15.6.6. List of variables for an execution

GET runtime/executions/{executionId}/variables?scope={scope}

Table 107. List of variables for an execution - URL parameters

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution to the variables for.
scope	No	String	Either local or global. If omitted, both local and global scoped variables are returned.

Table 108. List of variables for an execution - Response codes

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

Success response body:

[
   {
    "name":"intProcVar",
    "type":"integer",
    "value":123,
    "scope":"global"
   },
   {
    "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.

15.6.7. Get a variable for an execution

GET runtime/executions/{executionId}/variables/{variableName}?scope={scope}

Table 109. Get a variable for an execution - URL parameters

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution to the variables for.
variableName	Yes	String	Name of the variable to get.
scope	No	String	Either local or global. If omitted, local variable is returned (if exists). If not, a global variable is returned (if exists).

Table 110. Get a variable for an execution - Response codes

Response code	Description
200	Indicates both the execution 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 execution was not found or the execution does not have a variable with the given name in the requested scope (in case scope-query parameter was omitted, variable doesn’t exist in local and global scope). 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.

15.6.8. Create (or update) variables on an execution

POST runtime/executions/{executionId}/variables

PUT runtime/executions/{executionId}/variables

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

Table 111. Create (or update) variables on an execution - URL parameters

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution to the variables for.

Request body:

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



]

*Note that you can only provide variables that have the same scope. If the request-body array contains variables from mixed scopes, the request results in an error (400 - BAD REQUEST).*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 112. Create (or update) variables on an execution - Response codes

Response code	Description
201	Indicates the execution 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 execution was not found.
409	Indicates the execution 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.6.9. Update a variable on an execution

PUT runtime/executions/{executionId}/variables/{variableName}

Table 113. Update a variable on an execution - URL parameters

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution to update the variables for.
variableName	Yes	String	Name of the variable to update.

Request body:

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

More information about the variable format can be found in the REST variables section.

Table 114. Update a variable on an execution - 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":"global"
   }

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.

15.6.10. Create a new binary variable on an execution

POST runtime/executions/{executionId}/variables

Table 115. Create a new binary variable on an execution - URL parameters

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution 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.

• scope: Scope of variable that is created. If omitted, local is assumed.

Success response body:

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

Table 116. Create a new binary variable on an execution - 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 execution was not found.
409	Indicates the execution 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.6.11. Update an existing binary variable on a process-instance

PUT runtime/executions/{executionId}/variables/{variableName}

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

Parameter	Required	Value	Description
executionId	Yes	String	The id of the execution to create the new variable for.
variableName	Yes	String	The name of the variable to update.

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.

• scope: Scope of variable that is created. If omitted, local is assumed.

Success response body:

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

Table 118. 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 execution was not found or the execution 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.