Start Process Instance
Instantiates a given process definition. Process variables and business key may be supplied in the request body.
Method
POST /process-definition/{id}/start
POST /process-definition/key/{key}/start
(starts the latest version of the process definition which belongs to no tenant)
POST /process-definition/key/{key}/tenant-id/{tenant-id}/start
(starts the latest version of the process definition for tenant)
Parameters
Path Parameters
Name | Description |
---|---|
id | The id of the process definition to be retrieved. |
key | The key of the process definition (the latest version thereof) to be retrieved. |
tenant-id | The id of the tenant the process definition belongs to. |
Request Body
A JSON object with the following properties: (at least an empty JSON object {}
or an empty request body)
Name | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
variables | A JSON object containing the variables the process is to be initialized with. Each key corresponds to a variable name and each value to a variable value. A variable value is a JSON object with the following properties:
| ||||||||||||||||||
businessKey | The business key the process instance is to be initialized with. The business key uniquely identifies the process instance in the context of the given process definition. | ||||||||||||||||||
caseInstanceId | The case instance id the process instance is to be initialized with. | ||||||||||||||||||
startInstructions |
Optional. A JSON array of instructions that specify which activities to start the process instance at. If this property is omitted, the process instance starts at its default blank start event.
The instructions are executed in the order they are in. An instruction may have the following properties:
|
||||||||||||||||||
skipCustomListeners |
Skip execution listener invocation for activities that are started or ended as part of this request.
Note: This option is currently only respected when start instructions are submitted via the |
||||||||||||||||||
skipIoMappings |
Skip execution of input/output variable mappings for activities that are started or ended as part of this request.
Note: This option is currently only respected when start instructions are submitted via the |
||||||||||||||||||
withVariablesInReturn | Indicates if the variables, which was used by the process instance during execution, should be returned. Default value: false |
Result
A JSON object representing the newly created process instance. Properties are:
Name | Value | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | String | The id of the process instance. | ||||||||||||
definitionId | String | The id of the process definition. | ||||||||||||
businessKey | String | The business key of the process instance. | ||||||||||||
caseInstanceId | String | The case instance id of the process instance. | ||||||||||||
tenantId | String | The tenant id of the process instance. | ||||||||||||
ended | Boolean | A flag indicating whether the instance is still running or not. | ||||||||||||
suspended | Boolean | A flag indicating whether the instance is suspended or not. | ||||||||||||
links | Object | A JSON array containing links to interact with the instance. | ||||||||||||
variables | Object |
A JSON object containing a property for each of the latest variables.
The key is the variable name, the value is a JSON object of serialized variable values with the following properties:
|
Response Codes
Code | Media type | Description |
---|---|---|
200 | application/json | Request successful. |
400 | application/json | The instance could not be created due to an invalid variable value, for example if the value could not be parsed to an Integer value or the passed variable type is not supported. See the Introduction for the error response format. |
404 | application/json | The instance could not be created due to a non existing process definition key. See the Introduction for the error response format. |
500 | application/json | The instance could not be created successfully. See the Introduction for the error response format. |
Example
Starting a process instance at its default initial activity:
Request
POST /process-definition/aProcessDefinitionId/start
POST /process-definition/key/aProcessDefinitionKey/start
Request body:
{
"variables": {
"aVariable" : {
"value" : "aStringValue",
"type": "String"
},
"anotherVariable" : {
"value" : true,
"type": "Boolean"
}
},
"businessKey" : "myBusinessKey"
}
Response
{
"links": [
{
"method": "GET",
"href":"http://localhost:8080/rest-test/process-instance/anId",
"rel":"self"
}
],
"id":"anId",
"definitionId":"aProcessDefinitionId",
"businessKey":"myBusinessKey",
"tenantId":null,
"ended":false,
"suspended":false
}
Starting a process instance with variables in return:
Request
POST /process-definition/aProcessDefinitionId/start
POST /process-definition/key/aProcessDefinitionKey/start
Request body:
{
"variables":{
"aVariable" : {
"value" : "aStringValue",
"type": "String"},
"anotherVariable" : {
"value" : true,
"type": "Boolean",
"valueInfo" : {
"transient" : true
}
}
},
"businessKey" : "myBusinessKey",
"withVariablesInReturn": true
}
Response
{
"links": [
{
"method": "GET",
"href": "http://localhost:8080/rest-test/process-instance/aProcInstId",
"rel": "self"
}
],
"id": "aProcInstId",
"definitionId": "aProcessDefinitionId",
"businessKey": "myBusinessKey",
"ended": false,
"suspended": false,
"tenantId": null,
"variables": {
"anotherVariable": {
"type": "Boolean",
"value": true,
"valueInfo": {
"transient" : true
}
},
"aVariable": {
"type": "String",
"value": "aStringValue",
"valueInfo": { }
}
}
}
Starting a process instance at two specific activities:
Request
POST /process-definition/aProcessDefinitionId/start
POST /process-definition/key/aProcessDefinitionKey/start
Request Body:
{
"variables": {
"aProcessVariable" : {
"value" : "aStringValue",
"type": "String"
}
},
"businessKey" : "myBusinessKey",
"skipCustomListeners" : true,
"startInstructions" :
[
{
"type": "startBeforeActivity",
"activityId": "activityId",
"variables": {
"var": {
"value": "aVariableValue",
"local": false,
"type": "String"}
}
},
{
"type": "startAfterActivity",
"activityId": "anotherActivityId",
"variables": {
"varLocal": {
"value": "anotherVariableValue",
"local": true,
"type": "String"
}
}
}
]
}
Response
{
"links": [
{
"method": "GET",
"href":"http://localhost:8080/rest-test/process-instance/anId",
"rel":"self"
}
],
"id":"anId",
"definitionId":"aProcessDefinitionId",
"businessKey":"myBusinessKey",
"tenantId":null,
"ended":false,
"suspended":false
}