Skip to main content
Version: v2

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.

Process Definitions store the BPMN and DMN files that encode your orchestration logic. This API supports retrieving, searching, and deleting deployed definitions. Uploading a new definition and managing the maker-checker approval workflow — where a Maker uploads a definition and a different Checker must approve it before it becomes current — is handled by the Staged Process Definitions API.

Both BPMN (process flow) and DMN (decision table) files go through the same staged upload and approval flow — there is no separate endpoint for DMN files.

Definition lifecycle​

Upload (POST /stagedprocessdefinitions) → PENDING_APPROVAL → [Approve] → APPROVED → [Make current] → CURRENT
                                                            → [Reject]  → REJECTED

A definition must be made current before it can be started or linked to a CBE extension point. See the Staged Process Definitions API for the upload, approve, make-current, and reject endpoints.

Endpoint summary​

MethodPathDescription
GET/processdefinitions/{key}Get a specific definition (latest current version)
GET/processdefinitions/{key}/{version}Get a specific version of a definition
POST/processdefinitions:searchSearch process definitions
DELETE/processdefinitions/{key}Delete all versions of a definition

Searching definitions​

POST /processdefinitions:search lists deployed definitions. 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 deployed BPMN definition, filter on type only:

POST /api/processdefinitions: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" }
  ]
}
FieldRequiredOperatorsValues
typeYesEQUALSBPMN or DMN
processKeyNoEQUALS, STARTS_WITHProcess key, or the start of it
categoryNoEQUALSCORE_EXTENSION or PROCESS_ORCHESTRATION. Responses show these as core-extension and process-orchestration
versionNoEQUALS, MORE_THAN, LESS_THAN, BETWEEN (with secondValue)Version number. Only allowed with versions=ALL

Rules:

  • Each field can appear at most once, with up to 16 filter rows in total.
  • By default only the latest version of each definition is returned. Add the versions=ALL query parameter to return every version.
  • Results are sorted by processKey in ascending order. Use sortingCriteria to sort by processKey or version, for example "sortingCriteria": { "field": "version", "order": "DESC" }.
  • Use the offset and limit query parameters to page through results. The default limit is 50 and the maximum is 1000.

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

To search definitions that are still waiting for approval, use POST /stagedprocessdefinitions:search on the Staged Process Definitions API.

Uploading a definition​

Definitions are uploaded through the Staged Process Definitions API as a raw binary body — multipart/form-data is not supported:

POST /api/stagedprocessdefinitions
Accept: application/vnd.mambu.v2+json
Content-Type: application/octet-stream
Authorization: Basic <base64-encoded username:password>

[raw BPMN or DMN file bytes]

The response contains a numeric staged definition id — use it for the :approve, :make-current, and :reject calls on the Staged Process Definitions API.

Deletion constraint​

DELETE removes all versions of a process definition by key. It fails with 409 Conflict if any active process instances still reference the definition — cancel or complete them first.