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_signedaudit 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 key | Meaning |
|---|---|
id | Starts with a letter; letters, digits and _ only; at most 40 characters; unique in the form. |
label | What the signer reads. Required, at most 200 characters. |
type | text, textarea, number, date, select or checkbox. |
required | true or false (default false). A required checkbox must be ticked. |
options | select only: 1–50 distinct, non-blank choices. |
min, max | number: 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.
| Response | When |
|---|---|
422 with detail.field | A 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: null | form 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.
Process mining
Import what really happened — a CSV or XES event log, or your own run history — and see the process map with its variants, times and bottlenecks, compare it with a published version, and turn it into a draft.
Escalation, delegation and N-of-M approvals
Require several signatures on a gate, hand your gates to a delegate while you are away, assign a waiting gate to a named member, and let a deadline's escalation level reassign it — without anything ever signing or rerouting a run on its own.