Minctrl Docs
Guides

Import / export BPMN

Round-trip a process with BPMN 2.0 — export a saved process to XML, or import a model from Camunda, Signavio or Bizagi, see where it is ungoverned, and save it as a process of your company.

Minctrl processes interchange with BPMN 2.0, so you can hand a governed process to a modeling tool (Camunda, Signavio, Bizagi, bpmn.io) or bring a model authored elsewhere in and check it against the governance invariants. In the admin this is Processes → Import BPMN.

Export a saved process to BPMN 2.0 XML

curl -s "$API/process-templates/drafts/refund-approval/bpmn" \
  -H "Authorization: Bearer $TOKEN" \
  -o refund-approval.bpmn

The latest version is exported unless you pass ?version=N. The response is BPMN 2.0 XML with isExecutable="false" — an interchange artefact, not a runnable model. The mapping is:

Minctrl stepBPMN element
Agent stepserviceTask
Human gateuserTask (its form, if any, as a minctrl:form extension element; its approvals policy, if any, as minctrl:approvals)
Gatewaybranch / join gateway

The exported XML is for round-tripping into a modeling tool. Execution still happens in Minctrl via process runs — the BPMN export is not handed to a BPMN engine.

Import a BPMN model

Bring a model in with POST /process-templates/import-bpmn. The endpoint takes JSON with the BPMN XML as a string field (not a raw XML body). Wrap a file's contents with jq:

jq -n --rawfile xml model.bpmn '{xml: $xml}' \
  | curl -s -X POST "$API/process-templates/import-bpmn" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @-

Without save, this is a preview: nothing is stored. The response is the Minctrl canvas graph (nodes, edges) plus the live governance violations — so importing a third-party model immediately shows where it is ungoverned (for example, an irreversible step with no human gate on some path).

The XML must contain a <process> element and be at most 2 MB; malformed XML, a missing <process>, or a DOCTYPE / ENTITY declaration returns 400.

Save the imported model

Add "save": true to store the graph as the next version of a process in your company — through the same validation and audit entry as a canvas save:

jq -n --rawfile xml model.bpmn '{xml: $xml, save: true, slug: "refund-approval", name: "Refund approval"}' \
  | curl -s -X POST "$API/process-templates/import-bpmn" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @- \
  | jq '{saved: .saved.version, hash, executable_violations}'

slug defaults to the BPMN process id (lower-cased, other characters folded to -) and name to the BPMN process name; an existing slug gets a new version. The response adds saved (the stored version), hash (what a run would pin) and executable_violations. A complete process exported from Minctrl (__start__ and __end__ included) comes back with the same hash it left with.

A model from another tool has no governance decoration until you add it. Open the saved process on the canvas, assign risk tiers and gates, and save again — until you do, the validator flags irreversible steps that no human gate protects, and a run of a version with violations is refused with 422. See Design on the canvas.

See the API reference for the full BPMN and canvas schemas.

On this page