Version: v2

Staged process definitions

Non-Production Preview

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
POST	/stagedprocessdefinitions:search	Search staged definitions

Searching staged definitions

POST /stagedprocessdefinitions:search lists staged definitions, for example to build a review queue for Checkers. A response contains either BPMN or DMN definitions, never both, so every request must include a type filter. All other filters are optional. To list every staged BPMN definition that is waiting for approval:

POST /api/stagedprocessdefinitions:search?offset=0&limit=50
Accept: application/vnd.mambu.v2+json
Content-Type: application/json
Authorization: Basic <base64-encoded username:password>

{
  "filterCriteria": [
    { "field": "type", "operator": "EQUALS", "value": "BPMN" },
    { "field": "status", "operator": "EQUALS", "value": "PENDING_APPROVAL" }
  ]
}

Leave out the status row to list all staged BPMN definitions.

Field	Required	Operators	Values
type	Yes	EQUALS	BPMN or DMN
status	No	EQUALS	PENDING_APPROVAL, ACTIVE (approved), or REJECTED
processKey	No	EQUALS, STARTS_WITH	Process key, or the start of it
category	No	EQUALS	CORE_EXTENSION or PROCESS_ORCHESTRATION. Responses show these as core-extension and process-orchestration

Rules:

• Each field can appear at most once, with up to 16 filter rows in total.
• Results are sorted by processKey in ascending order. Use "sortingCriteria": { "field": "processKey", "order": "DESC" } to reverse the order.
• Use the offset and limit query parameters to page through results. The default limit is 50 and the maximum is 1000.
• Search results do not include the definition content. Use GET /stagedprocessdefinitions/{id} to get it.

A request that breaks one of these rules returns 400 Bad Request with a message that names the field.

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