Minctrl Docs
Guides

Run a governed process

Start a run of a process saved in your company, understand why it parks, resume it on the right gate, and keep irreversible tools shadowed.

A run executes the published version of a process saved in your company, step by step (see Publishing processes). It proceeds on its own until governance decides a step needs a person — then it parks. This guide covers the start → park → resume loop and the two things people get wrong: naming the gate and shadowing.

A run needs a saved process. If your company has none yet, import one first (see the Quickstart) or save one from the canvas (Design on the canvas). List what you have:

curl -s "$API/process-templates/drafts" -H "Authorization: Bearer $TOKEN" \
  | jq '[.[] | {slug, version, state, published_version, violations}]'

Start a run

curl -s -X POST "$API/process-runs/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "prior-auth",
    "draft": true,
    "inputs": { "member_id": "M-10293", "procedure_code": "27447", "risk": "fails criteria" },
    "auto_resolve": true
  }'
  • vertical — the slug of the process to run. Required.
  • draft — true for a process saved in your company. This is what the admin sends.
  • draft_version — which saved version to run; omitted means the published one (409 when nothing is published). A version that is not published is refused with 409, unless it is its author's shadow test run.
  • shadow — true for a shadow test run: every connector is shadowed for the run's whole life. Only the author may test-run a version that is not published.
  • inputs — the seed facts steps and connectors read from.
  • auto_resolve — run the autopilot (default true): auto-execute steps the resolver clears. With it off, the start stops at the first step that would otherwise auto-clear.

The run is pinned to the version it started on: the response carries graph_version and graph_hash, and every later resume re-drives that same graph, even if the process is edited or another version is published meanwhile. A version with governance violations is refused with 422 and the list of violations; an unknown slug returns 404.

Runs without draft

With draft omitted or false, vertical is looked up among the bundled example graphs by name instead of your company's processes. The API still accepts this for compatibility; the admin does not use it, and a process you import or build is only reachable with "draft": true.

Why a run parks

A run parks when it reaches a gate — a step whose risk tier requires a human verdict (see the Governance model). The response names the gate twice: parked_at is the gate's label (e.g. gate:medical-director-signoff) and trace.parked_step is its step-id (e.g. signoff). Read the current state any time:

curl -s "$API/process-runs/$RUN_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '{status, parked_at, step: .trace.parked_step, visit: .trace.parked_visit, sla}'

To see which steps are gates before running, read the saved process:

curl -s "$API/process-templates/drafts/prior-auth" -H "Authorization: Bearer $TOKEN" \
  | jq '[.canvas.nodes[] | select(.kind == "gate") | {id, gate, human}]'

Resume on the right gate

curl -s -X POST "$API/process-runs/$RUN_ID/resume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gate": "signoff",
    "decision": "approved",
    "feedback": "Chart reviewed."
  }'
  • gate — the step-id the run parked on (trace.parked_step) or its parked_at label.
  • decision — approved, denied, or a branch label the gate routes on.
  • feedback — a note stored with who signed, their role and when. Optional for an approval; required for a denial (422 without it).
  • form — the values of the gate's form, when it declares one (see Forms in the gate); a value the form refuses returns 422 naming the field, and nothing is signed.

A gate with an approvals policy (N-of-M) records each approval and stays parked until the last one: the response is the run, still awaiting_human, with approvals saying how many of how many have signed. See Escalation, delegation and N-of-M approvals.

Signing needs the manager role or above (403 otherwise). With separation of duties on (the default), a person who signed one gate of a run cannot sign a different gate of the same run (409). A run that is not waiting for a person returns 409, and so does a gate that names neither the parked step-id nor its label — the response says which gate the run waits at, and nothing is recorded.

A decision must name an outcome of the gate: approved or denied, or — on a gate that routes to several outcomes — one of its branch labels. Anything else returns 422 with the outcomes the gate offers, and nothing is signed.

Keep irreversible tools shadowed

A run can auto-execute a step whose tool does something irreversible once its gate is signed. Minctrl keeps those tools shadowed (no real call) until you opt in per connector; the step's tool_results in trace.events then show "shadow": true. During a governed rollout, keep the connector shadowed and let the gate before it collect a human verdict — then un-shadow once you trust the flow. See Connect a step to your API.

The loop

  1. POST /process-runs/ with your process slug and "draft": true → the run executes the published version, then parks at a gate.
  2. GET /process-runs/{id} → read trace.parked_step.
  3. POST /process-runs/{id}/resume with that step-id and a decision → the run continues.
  4. Repeat until status is completed.

On this page