Overview
The goal of the REST API is to provide access to all relevant interfaces of the engine.
Structure
These documents explain all existing methods in the REST API. For each method they provide:
- An informal description
- HTTP verb and URL
- Possible query, path or message body parameters
- A detailed description of the response content
- Possible response codes
- A brief example request and response
Engine Usage
The methods as described work on the default process engine as given by the available ProcessEngineProvider service.
You may prepend /engine/{name} to any of the methods (unless otherwise documented) to access another engine where {name} is the name of the process engine as returned by ProcessEngine#getName(), e.g., /engine/myEngineName/task.
Error Handling
For every method this documentation gives possible HTTP status codes. The error explanations do not cover all possible error causes that may arise when the request is served, for example, most of the requests will not work properly if there are problems with database access. Any of these undocumented errors will be translated to a HTTP 500 error.
All errors also provide a JSON response body of the form:
{
"type" : "SomeExceptionClass",
"message" : "a detailed message",
"code" : 10000
}
Authorization Exceptions
If an already authenticated user interacts with a resource in an unauthorized way, the status code of the response will be set to 403 Forbidden. Details about the unauthorized interaction are provided in the response body.
Type
AuthorizationException
Response Body
{"type" : "AuthorizationException",
"message" : "The user with id 'jonny' does not have 'DELETE' permission on resource 'Mary' of type 'User'.",
"code" : 0,
"userId" : "jonny",
"permissionName" : "DELETE",
"resourceName" : "User",
"resourceId" : "Mary"}
Migration Validation Exceptions
If a migration plan from one process definition version to another is not valid, a migration exception is thrown. It can be a migration plan validation exception where the plan itself is not valid, e.g., it contains an invalid instruction. Or it can be a migrating process instance validation exception when a migration plan cannot be applied to a specific process instance, e.g., an active activity was not mapped by the migration plan.
Migration Plan Validation Exceptions
Type
MigrationPlanValidationException
Response Body
A JSON object with the following properties:
| Name | Type | Description |
|---|---|---|
| type | String | The type of exception, here MigrationPlanValidationException. |
| message | String | The error message. |
| code | Number | The code allows your client application to identify the error in an automated fashion. You can look up the meaning of all built-in codes and learn how to add custom codes in the User Guide. |
| validationReport | Object | A JSON object containing details about all detected validation errors. Its properties are described below. |
Every validation report object contains the following properties:
| Name | Type | Description |
|---|---|---|
| instructionReports | Array |
A JSON array describing a single instruction validation report.
Each report object consists of an instruction that is
invalid and a failures array containing the validation
messages for this instruction.
|
Example
{
"type": "MigrationPlanValidationException",
"message": "ENGINE-23001 Migration plan for process definition 'invoice:1:8aa1533c-23e5-11e6-abb7-f6aefe19b687' to 'invoice:2:8accd012-23e5-11e6-abb7-f6aefe19b687' is not valid:\n\t Migration instruction MigrationInstructionImpl{sourceActivityId='approveInvoice', targetActivityId='assignApprover', updateEventTrigger='false'} is not valid:\n\t\tActivities have incompatible types (UserTaskActivityBehavior is not compatible with DmnBusinessRuleTaskActivityBehavior)\n",
"code" : 0,
"validationReport": {
"instructionReports": [
{
"instruction": {
"sourceActivityIds": [
"approveInvoice"
],
"targetActivityIds": [
"assignApprover"
],
"updateEventTrigger": false
},
"failures": [
"Activities have incompatible types (UserTaskActivityBehavior is not compatible with DmnBusinessRuleTaskActivityBehavior)"
]
}
]
}
}
Migrating Process Instance Validation Exceptions
Type
MigratingProcessInstanceValidationException
Response Body
A JSON object with the following properties:
| Name | Type | Description |
|---|---|---|
| type | String | The type of exception, here MigratingProcessInstanceValidationException. |
| code | Number | The code allows your client application to identify the error in an automated fashion. You can look up the meaning of all built-in codes and learn how to add custom codes in the User Guide. |
| message | String | The error message. |
| validationReport | Object | A JSON object containing details about all detected validation errors. Its properties are described below. |
Every validation report object contains the following properties:
| Name | Type | Description |
|---|---|---|
| processInstanceId | String | The id of the process instance that cannot be migrated when following the migration plan. |
| failures | Array | An array of general failure messages, which are not related to a specific activity or transition. |
| activityInstanceValidationReports | Array |
An array of JSON objects describing the single activity instance
validation errors. Each activity instance validation report
consists of a migrationInstruction, if the error is
related to an existing migration instruction, the
activityInstanceId and sourceScopeId
of the activity which cannot be migrated and an array
failures, which is a list of all validation error
messages for this report.
|
| transitionInstanceValidationReports | Array |
An array of JSON objects describing the single transition instance
validation errors. Each transition instance validation report
consists of a migrationInstruction, if the error is
related to an existing migration instruction, the
transitionInstanceId and sourceScopeId
of the transition which cannot be migrated and an array
failures, which is a list of all validation error
messages for this report.
|
Example
{
"type": "MigratingProcessInstanceValidationException",
"message": "ENGINE-23004 Cannot migrate process instance '96dc383f-23eb-11e6-8e4a-f6aefe19b687':\n\tCannot migrate activity instance 'approveInvoice:f59925bc-23eb-11e6-8e4a-f6aefe19b687':\n\t\tThere is no migration instruction for this instance's activity\n\tCannot migrate transition instance 'f598897a-23eb-11e6-8e4a-f6aefe19b687':\n\t\tThere is no migration instruction for this instance's activity\n",
"code": 0,
"validationReport": {
"processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687",
"failures": [],
"activityInstanceValidationReports": [
{
"migrationInstruction": null,
"activityInstanceId": "approveInvoice:f59925bc-23eb-11e6-8e4a-f6aefe19b687",
"sourceScopeId": "approveInvoice",
"failures": [
"There is no migration instruction for this instance's activity"
]
}
],
"transitionInstanceValidationReports": [
{
"migrationInstruction": null,
"transitionInstanceId": "f598897a-23eb-11e6-8e4a-f6aefe19b687",
"sourceScopeId": "ServiceTask_1",
"failures": [
"There is no migration instruction for this instance's activity"
]
}
]
}
}
Parse Exceptions
If the process bpmn resource cannot be parsed during deployment, the deployment of it will fail and the status code of the response will be set to 400 Bad Request. Details about the parsing problems are provided in the response body.
Type
ParseException
Response Body
{
"type": "ParseException",
"message": "ENGINE-09005 Could not parse BPMN process. Errors: Exclusive Gateway 'ExclusiveGateway_1' has outgoing sequence flow 'SequenceFlow_0' without condition which is not the default flow.",
"code" : 0,
"details": {
"invoice.bpmn": {
"errors": [
{
"message": "Exclusive Gateway 'ExclusiveGateway_1' has outgoing sequence flow 'SequenceFlow_0' without condition which is not the default flow.",
"line": 77,
"column": 15,
"mainBpmnElementId": "ExclusiveGateway_1",
"bpmnElementIds": [
"ExclusiveGateway_1",
"SequenceFlow_0"
]
}
],
"warnings": [
{
"message": "It is not recommended to use a cancelling boundary timer event with a time cycle.",
"line": 87,
"column": 20,
"mainBpmnElementId": "BoundaryEvent_1",
"bpmnElementIds": [
"BoundaryEvent_1"
]
}
]
}
}
Query Maximum Results Limit Exceptions
When the maximum results limit of a query is exceeded, an exception is thrown which results in an HTTP status code 400.
Exception codes
Whenever an error occurs, the REST API exposes a property "code" with a numeric code as value in
the response body of the failed request. Like this, your client application can handle the error in
a reliable and automated fashion. The type property might be too coarse-grained, and the message
property might change with newer versions.
You can look up the meaning of all built-in codes and learn how to add custom codes in the User Guide.
Authentication
The REST API ships with an implementation of HTTP Basic Authentication. By default it is switched off (in the rest-api web application and therefore also in the pre-built CIB seven distributions). You can activate it by adding a servlet filter as described in the Authentication section.