Minctrl Docs
Guides

Forms in the gate

Give a human gate a form — the facts the signer must fill in to sign. The server checks every value, records it with the signature and the audit entry, and hands it to the steps after the gate.

A gate asks a person for a verdict. Often the verdict is not enough: the next step needs the settlement amount the manager agreed to, the reason code a reviewer chose, or a tick that identity was verified. A gate can declare a form for those facts. The sign-off card shows it, the person fills it in, and the values travel with the signature:

  • into the run's decisions — the record a run is replayed from;
  • into the gate_signed audit entry, next to who signed, in which role, and when;
  • into the run state of the steps after the gate, as gate_form.<step_id>.<field_id>.

The server checks every value. The sign-off card only helps: it keeps Sign off until the required fields are valid, and shows a field the server refused under that field.

Declare a form

On the canvas, select a gate and turn on The signer fills in a form in the inspector. Add fields, give each a label, a type, and whether it is required. The field id follows the label until you change it; it is the name the next steps read.

In a minctrl.process/v1 file or a canvas graph, a form sits on a gate node:

{
  "id": "settle",
  "kind": "gate",
  "label": "Manager approves the settlement",
  "human": "collections-manager",
  "gate": "gate:settlement-signoff",
  "tier": "high",
  "form": {
    "fields": [
      { "id": "amount", "label": "Settlement amount", "type": "number", "required": true, "min": 0, "max": 5000 },
      { "id": "reason", "label": "Reason code", "type": "select", "required": true, "options": ["hardship", "dispute", "goodwill"] },
      { "id": "pay_by", "label": "Pay by", "type": "date", "min": "2026-01-01" },
      { "id": "memo", "label": "Memo", "type": "textarea", "max": 500 },
      { "id": "verified", "label": "Identity verified", "type": "checkbox", "required": true }
    ]
  }
}
Field keyMeaning
idStarts with a letter; letters, digits and _ only; at most 40 characters; unique in the form.
labelWhat the signer reads. Required, at most 200 characters.
typetext, textarea, number, date, select or checkbox.
requiredtrue or false (default false). A required checkbox must be ticked.
optionsselect only: 1–50 distinct, non-blank choices.
min, maxnumber: bounds. text / textarea: length in characters. date: YYYY-MM-DD. Not on select or checkbox; min ≤ max.

A form has 1–20 fields. Only a gate carries one. A text field with no max holds up to 500 characters, a textarea up to 5000; a declared max may not exceed 1000 for a text field or 10000 for a textarea (refused at save). The sign-off note (feedback) holds at most 5000 characters, and the whole POST …/resume body is capped at 256 KiB (413, nothing signed; RESUME_MAX_BYTES changes it).

A form that breaks these rules is a violation: the canvas lists it live (POST /process-templates/validate), and saving or importing the graph is refused with 422 and the list of what is wrong — a form is what signatures are checked against, so a broken one is never stored.

Sign a gate that has a form

The Sign-off queue shows the form on the decision card, under the outcomes. Every field has its label; a required one is marked *. Pick an outcome, fill the form in, sign.

  • Sign stays off until every required field is valid. Pressing it says which field is missing and puts the cursor there.
  • A denial need not fill required fields — a person refusing a settlement should not have to invent its amount. Anything they do fill in is still checked. A denial still needs its reason in the note.
  • Bulk approval sets a gate with a form aside for its own card, and the Runs page sends you to the Sign-off queue for it.
  • The typed confirmation of a live irreversible gate and separation of duties stay as they are: the form adds to the card, it replaces neither.

Over the API, send the values as form on resume:

curl -s -X POST "$API/process-runs/$RUN_ID/resume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gate": "settle",
    "decision": "approved",
    "feedback": "Hardship plan agreed on the call.",
    "form": { "amount": 1200, "reason": "hardship", "pay_by": "2026-11-30", "verified": true }
  }'

A number is a JSON number (not "1200"), a date is YYYY-MM-DD, a checkbox is true or false. Text is trimmed. A field left out or blank is recorded as null (a checkbox as false), so the record says what every field was.

What is refused

The checks run right after the gate and verdict checks, before anything is recorded. A refusal signs nothing: the run stays parked, no note, no decision, no audit entry.

ResponseWhen
422 with detail.fieldA required field is missing, a value has the wrong type or is out of range, a choice is not one of the options, or a key names no field of the form.
422, detail.field: nullform was sent to a gate that has no form.
{
  "detail": {
    "message": "Settlement amount: at most 5000 — nothing was signed.",
    "field": "amount",
    "errors": [{ "field": "amount", "message": "Settlement amount: at most 5000" }]
  }
}

The other refusals of resume (403 for a role that may not sign, 409 for a run not waiting or a wrong gate, 409 for separation of duties, 422 for a denial without a reason) are unchanged.

Where the values go

Decisions. The run's decisions gains a reserved key, __forms__, holding the values per step and per visit — the same shape as the verdicts:

{ "settle": ["approved"], "__forms__": { "settle": [{ "amount": 1200, "reason": "hardship", "pay_by": "2026-11-30", "memo": null, "verified": true }] } }

A run that cycles back to the same gate asks for the form again on the next visit. Gate statistics ignore the __forms__ key.

Audit. The gate_signed entry carries form next to decision, note, by, role and the graph hash — the hash-linked chain proves what was filled in, not only that a gate was signed. The run's notes for the gate carry the same values.

The next steps. After the gate, the run state holds one key per field: gate_form.settle.amount, gate_form.settle.reason, … A connector reads them like any other state key — in body_map / query_map, or as a {…} placeholder in its path:

{
  "base_url": "https://billing.example.com",
  "method": "POST",
  "path": "/plans/{case_id}",
  "body_map": { "amount": "gate_form.settle.amount", "reason": "gate_form.settle.reason" }
}

The trace. The gate's human-cleared event carries form, and the Runs page lists the values under it by label.

Replay and pinned graphs

A run is pinned to the graph it started on, form included. The values are replay input: every drive of the run rebuilds the state the next steps read from decisions, so the same run replays to the same result. Editing the process while a run is parked does not change the form that run is signed against — the next run starts on the new version.

On the durable runtime (PROCESS_RUNTIME=temporal), the values ride in the resume signal as a fourth argument, and only when the gate has a form; a signal without one is exactly what a worker from before forms understands.

JSON and BPMN

A form is part of the graph, so it is in the minctrl.process/v1 export and changes the graph hash (key order and a missing "required": false do not). In BPMN, a gate's form is an extension element of its userTask, read back field for field on import:

<bpmn:userTask id="Node_settle" name="Manager approves the settlement" minctrl:stepId="settle" …>
  <bpmn:documentation>human gate · signed by: collections-manager · …</bpmn:documentation>
  <bpmn:extensionElements>
    <minctrl:form>
      <minctrl:field id="amount" label="Settlement amount" type="number" required="true" min="0" max="5000"/>
      <minctrl:field id="reason" label="Reason code" type="select" required="true">
        <minctrl:option>hardship</minctrl:option><minctrl:option>dispute</minctrl:option>
      </minctrl:field>
    </minctrl:form>
  </bpmn:extensionElements>
</bpmn:userTask>

Other modeling tools keep or skip the foreign extension; a Minctrl export comes back with the same hash it left with.

On this page