Invoke a workflow

A role’s form_schema can place a control that starts another workflow: a link, an icon link, or a button. It either posts the workflow at once with a payload mapped from the escalation, or opens the workflow’s own invoke form in a dialog, prefilled from the same mapping. The control reuses the Invoke Tool page end to end: the same per-caller list decides who sees it, the same input_schema gate validates the payload, the same registered icon leads the label, and the outcome arrives over the same live events.

The field is display-only. It carries no answer, is dropped from the resolver payload, and stays out of required.

"print_label": {
  "type": "string",
  "readOnly": true,
  "x-lt-widget": "invoke",
  "x-lt-invoke": {
    "workflow": "printLabel",
    "data": { "order": { "id": "{{metadata.orderId}}" }, "copies": 1 },
    "metadata": { "escalationId": "{{escalation.id}}" },
    "modal": true
  },
  "title": "Print label",
  "description": "Prints the shipping label for this order",
  "x-lt-section": "Tools",
  "x-lt-span": 2,
  "x-lt-showIf": "metadata.orderId"
}

The declaration

Key	Type	Meaning
workflow	string	The workflow_type to start. Required
data	object	The nested data the invoke API receives. Leaves interpolate {{domain.path}} tokens against the escalation context. Defaults to {}
metadata	object	Extra run metadata, merged over the workflow’s declared envelopeSchema.metadata. Same interpolation
modal	boolean	true opens the workflow’s invoke form prefilled; false (default) posts data at once
confirm	string	Direct mode only: a prompt shown before the post. Tokens interpolate
variant	"link" or "button"	The control’s shape. Defaults to link
icon	boolean	Lead the label with the workflow’s registered icon. Defaults to true

The field’s title is the label; without one the workflow type reads as a title (printLabel becomes Print Label). description renders as the helper line beneath. Every layout token composes: x-lt-section, x-lt-span, x-lt-showIf, x-lt-order.

Mapping values

Write data once, in the shape the workflow receives. Direct mode posts it as resolved. Modal mode prefills the workflow’s input_schema by inverting each field’s x-lt-bind, so a field bound to machine.serialNumber opens holding data.machine.serialNumber. A workflow without an input_schema gets its envelope template form with data merged over the template.

Interpolation keeps types:

Leaf	Resolves to
"{{metadata.copies}}"	The raw context value: a number stays a number, a boolean a boolean, an array an array
"ORD-{{metadata.orderId}}"	A string
A token whose value is missing or null	The key is omitted, so the workflow’s own defaults apply
A mixed string with any missing segment	The key is omitted
1, true, "plain text"	Passed through unchanged

Objects and arrays recurse. The domains are the escalation form’s: escalation, metadata, envelope, payload, lookup, and the live resolver values, so a mapping can carry what the person has typed so far.

Who sees it

The control renders only for workflows the signed-in user may invoke, read from the same per-caller list that drives the Invoke Tool page. A workflow outside that list leaves no trace in the form, and the server runs the same check on the post. The control follows the form’s claim state: it is live once the person has claimed the escalation, and it leaves the form once the escalation is resolved, cancelled or expired.

One request serves every invoke field on the page, and the list is shared with the rest of the dashboard’s cache.

Direct mode

Clicking the control posts data with the workflow’s declared metadata (plus the field’s metadata mapping). The control reads Working… while the run is in flight, then Completed with the returned data as an outline beneath, or Failed with the reason. The outcome arrives over the same system.workflow.{id}.completed and .failed events the Invoke Tool page follows. Once the run settles, the control returns beneath the result, ready for another run. A warning offers to reconnect live events when they are off.

When the target declares an input_schema, the payload is checked against it before the post with the shared validation pass. Violations, from that check or from a server 422, list beneath the control with an Open form action that opens the workflow’s form prefilled, so the person completes what the mapping could not supply. A mapping meant for direct mode should satisfy the schema on its own; declare confirm when the action deserves a second look.

Modal mode

"modal": true opens the workflow’s invoke form in a dialog headed by its icon and title. It is the full x-lt-* form when the workflow declares an input_schema (pinned lookups resolved, conditional sections, the shared validation pass), and the envelope template form otherwise. Prefilled values sit in their fields, ready to change. Issues and the form’s x-lt-help render inside the dialog.

Submit posts exactly as the Invoke Tool page does, and the dialog becomes a receipt with one action:

State	The dialog shows
Working	The workflow’s icon, Working… and a Close control. Closing leaves the run going
Completed	Completed, the returned data as an outline, and a Done button
Failed	Failed with the reason. Try again returns to the form holding what was typed; Close dismisses

Escape and the close control dismiss the dialog; the backdrop keeps it open. Each opening starts clean.

Example

A machine-service role’s work form offers a set of machine tools for the machine on screen. Its escalations carry metadata.serialNumber, so the dialog opens with the serial already chosen:

machine_tools: {
  type: 'string',
  readOnly: true,
  'x-lt-widget': 'invoke',
  'x-lt-invoke': {
    workflow: 'machineTools',
    modal: true,
    data: { machine: { serialNumber: '{{metadata.serialNumber}}' } },
  },
  'x-lt-section': 'Tools',
  'x-lt-span': 2,
  title: 'Machine tools',
  description: 'Reprint a label, run a calibration, or report this machine offline',
}

Invoke forms shows the form the dialog opens.