Processinstances overview
The Process Orchestration APIs are currently available as a Non-Production Preview (NPP) feature and are not available to all clients. For more information, see Process Orchestration.
Process instances are only available for External Orchestration pattern processes. Core Extensions and API Composition processes execute synchronously within a CBE request and do not create persistent instances.
The Process Instances API provides full lifecycle management for External Orchestration process instances. Use it to start new instances, inspect running or historical instances, manage process variables, cancel running instances, and search across all instances.
External Orchestration processes run asynchronously and create persistent instances — this API is your primary interface for interacting with them.
Endpoint summary
| Method | Path | Description |
|---|---|---|
POST | /processinstances/{processDefinitionKey}:start | Start a new process instance |
GET | /processinstances/{processInstanceId} | Get historical data for a specific instance |
GET | /processinstances/{processInstanceId}/history/activities | List historical activities for an instance |
GET | /processinstances/{processInstanceId}/history/variables | List historical variables for an instance |
POST | /processinstances/{processInstanceId}/variables | Set multiple process-scoped variables atomically |
PUT | /processinstances/{processInstanceId}/variables/{name} | Set a single process-scoped variable |
POST | /processinstances/{processInstanceId}:cancel | Cancel a running process instance |
GET | /processinstances/{processInstanceId}/jobs | List background jobs (including dead-letter jobs) for an instance |
GET | /processinstances/{processInstanceId}/job-logs | List job execution logs for an instance |
POST | /processinstances/{processInstanceId}/jobs/{jobId}:retry | Retry a dead-letter job |
DELETE | /processinstances/{processInstanceId}/jobs/{jobId} | Delete a dead-letter job |
POST | /processinstances:search | Search process instances |
Starting a process instance
Start an External Orchestration process by providing the process key and any input variables the process requires. Input variables are passed as a flat JSON object.
Managing process variables
You can read and write process-scoped variables at runtime. Writing variables allows your external system to inject data into a running process.
Cancelling an instance
Cancel a running instance to terminate it before it reaches an end event. Cancellation is immediate and cannot be undone.
Instance status values
| Status | Description |
|---|---|
RUNNING | Process is currently executing or waiting at a human task, callback, or timer |
COMPLETED | Process reached an end event successfully |
FAILED | Process encountered an unhandled error and terminated |
CANCELLED | Process was cancelled externally via the cancel endpoint |