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.bpmnThe 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 step | BPMN element |
|---|---|
| Agent step | serviceTask |
| Human gate | userTask (its form, if any, as a minctrl:form extension element; its approvals policy, if any, as minctrl:approvals) |
| Gateway | branch / 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.
Design on the canvas
Author a governed process on the canvas — place nodes, give them risk tiers and gates, validate the graph live, and save it as a versioned process of your company.
Set up your team
Register (open), get your auto-created company, then invite members and assign roles — all company-scoped, so a teammate only ever sees your company's data.