Stagedprocessdefinitions 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.
The Staged Process Definitions API covers the maker-checker approval workflow for BPMN and DMN process definitions. When a Maker uploads a new definition, it is created as a staged record in PENDING_APPROVAL status, identified by a numeric id. A different user (the Checker) must review and approve or reject it, then make it current before it can be started or linked to a CBE extension point.
This enforces a four-eyes principle — no user can both submit and approve the same definition.
Definition lifecycle
Upload (POST /stagedprocessdefinitions) → PENDING_APPROVAL
↓
[Approve] → APPROVED → [Make current] → CURRENT
[Reject] → REJECTED (can be re-uploaded)
Endpoint summary
| Method | Path | Description |
|---|---|---|
POST | /stagedprocessdefinitions | Upload a BPMN or DMN file as a raw binary body — creates a staged record in PENDING_APPROVAL |
GET | /stagedprocessdefinitions/{id} | Get a staged definition with its content, by numeric id |
POST | /stagedprocessdefinitions/{id}:approve | Approve a staged definition |
POST | /stagedprocessdefinitions/{id}:make-current | Deploy an approved definition to the engine, making it the current version (idempotent) |
POST | /stagedprocessdefinitions/{id}:reject | Reject a staged definition, with a reason |
Uploading a definition
POST /api/stagedprocessdefinitions
Accept: application/vnd.mambu.v2+json
Content-Type: application/octet-stream
Authorization: Basic <base64-encoded maker-username:password>
[raw BPMN or DMN file bytes]
The response contains the staged definition's numeric id — the Checker needs it for the approve, make-current, and reject calls.
Approving a definition
The approving user's credentials must differ from the submitting user's. On approval, the definition moves to APPROVED status.
POST /api/stagedprocessdefinitions/1:approve
Accept: application/vnd.mambu.v2+json
Authorization: Basic <base64-encoded checker-username:password>
Attempting to approve your own submission returns 422 Unprocessable Entity.
Making a definition current
An APPROVED definition is not yet active. Deploy it to the engine to make it current:
POST /api/stagedprocessdefinitions/1:make-current
Accept: application/vnd.mambu.v2+json
Authorization: Basic <base64-encoded checker-username:password>
Calling this on a definition that is already current succeeds (idempotent). Calling it before the definition is APPROVED returns 400 Bad Request.
Rejecting a definition
Provide a reason for the rejection so the Maker understands what needs to be corrected:
POST /api/stagedprocessdefinitions/1:reject
Accept: application/vnd.mambu.v2+json
Content-Type: application/json
Authorization: Basic <base64-encoded checker-username:password>
{
"reason": "Process logic does not match the approved spec. Please revise the error handling on the fee calculation branch."
}
A rejected definition moves to REJECTED status. The Maker can upload a corrected version, which is staged as a new definition.
Response codes for approve, make-current, and reject
| Status | Description |
|---|---|
200 OK | Action successful — definition status updated |
400 Bad Request | Business rule violation — for example, making current a definition that isn't yet APPROVED |
404 Not Found | Staged definition not found |
422 Unprocessable Entity | Self-approval attempt — approver and submitter are the same user |