Overview
Workflow Designer
Visual workflow designer on route #/workflow-designer. It models a process as a graph of nodes and connections, saves it as metadata and executes it through the workflow runner (#/workflow-runner/<graph-id>).
Scope
- Workflow graph modeling with nodes, connections and operational metadata.
- Assisted authoring: starter templates, graph validation, guided configuration dialogs, inline guide.
- Configuration of reusable processes executed by the workflow runner.
Workflow Palette
- Start: process entry node (with optional menu entries).
- Route: a step where users work the records of an app list.
- Action: application operation (table action, row action or chained internal action) triggered from a step.
- Condition: logical branching with true/false paths on a record expression.
- Switch: N-way branching — a JS formula computes a value and each condition tests it (
resultExpressiontoken); the first branch whose test is true routes the flow, otherwise theelsebranch is followed. Each added condition creates a new output socket (a polygon vertex, with the condition as tooltip). - Timer: reminder / SLA on a state, projected onto the scheduler.
- Split ∥ / Join ∥: parallel gateways — the split spawns parallel tasks on a route, the join proceeds once all tasks are closed.
- End: explicit flow termination.
Assisted authoring
The designer supports building a workflow from scratch:
- Starter templates: "New from template" generates a ready-made graph for the common patterns (simple approval, claim/release queue, threshold chain, parallel tasks). Pick the main route and — where needed — the state field: graph, actions and transitions are created already wired.
- Graph validation (lint): "Validate graph" reports issues before saving (start with no outlets, unreachable nodes, action without target, empty condition, dead branch, incomplete timer/split, permission with an unknown role). Clicking a finding focuses the canvas on the affected node. Saving is never blocked: with open findings a summary appears with "Save anyway".
- Guided configurations: timer and split dialogs use dropdowns and a route autocomplete (same source as the designer properties) instead of free-text fields typed from memory.
- Onboarding and guide: a fresh canvas shows a first-steps checklist; the palette has descriptive tooltips; the "Quick guide" entry shows the shape legend and a glossary (bundle, transition, guard, permission, internal action).
Transitions and permissions
- A transition is metadata authored on a connection (click the small square at the arc midpoint): event, guard (JS expression on the record) and permission.
- Permissions work in two ways: on a route→action arc they hide the action from non-allowed roles; on the navigation path they block the transition. Granting mode (only the selected roles) or denying (everyone except the selected ones).
- On save, transitions are projected onto a queryable table; the graph remains the source of truth.
- On the server: when the written route is bound to a workflow (it has a bundle in a saved graph, even a context-only one) the bundle rules always apply, also outside the runner. With the runner context that graph applies, and an action allowed to the role can write even if the bundle denies edit: the action on the route's step, the action whose saved callback writes the route (e.g.
route: 'fatture_ricevute') and the parallel split creating its tasks there all count. Without context every bundle of the route applies and the deny wins; routes without a workflow are unchanged. The action's write names the transition node (the runner adds it to the context by itself,workflowActionNodeId): the deny is lifted only if that node, in the saved graph, performs that write on that route and the role can walk the edges leading to it, and if the record is among those the user sees in the node's starting step (same view, filters and row restriction as that step's list; for internal actions and splits the step the transition leads to also counts, and for a split the source record is checked). Without a node, with a node that does not qualify or with a record outside the step, the write is refused with a translated message.
Email node
The Email node (internal action type 101) is configured with right-click → Configure email: record route, recipients, subject and body, with record fields in double braces ({{fornitore_email}}). The server reads the record with the permissions of whoever runs the action and sends only what the node defines; the callback passes the node and the record:
await wtoolbox.enqueueEmail({ nodeId: 'i_email', relatedRoute: 'wf_ap_esiti', relatedPk: row.id });Sending rules and limits: Mailing page.
Action chain and payload
Connecting an action's output socket to other internal actions (scope "Internal (chained)") builds a chain that runs in order after the click, handing a payload from link to link.
The payload contract
- Trigger action (the toolbar button): the callback body lives inside a
Promise— the payload is delivered with `resolve(value)`, NOT withreturn(areturnexits the executor without resolving: the payload would arrive asundefined). - Internal actions: the callback receives the `payload` variable in scope (the previous link's value) in addition to
datasource, metaInfo, record, wtoolbox. A `return value` works here and becomes the payload of the next link; noreturn(orundefined) = pass-through (the previous payload continues unchanged). - The chain only follows actions with the "Internal" scope (plus the Split ∥, which receives the payload and returns it enriched with
tasksCreated): a regular action connected downstream is not auto-executed — that arc carries navigation/transition semantics, and the chain stops there. - An error in an internal action is reported but does not block the rest of the chain.
- Each link stores its payload per node: any callback can read it back with
wtoolbox.getWorkflowRouteNodePayload('<nodeId>')(useful to retrieve the trigger's value in a long chain).
Example:
// TRIGGER action callback (toolbar button)
const row = wtoolbox.unwrapEntity(record);
const esito = await wtoolbox.dataService.update(
Object.assign({}, row, { po_stato: 'APPROVATO' }), row, datasource);
resolve(esito); // <-- hands the payload to the chain
// INTERNAL action callback connected to its out socket
The callback and formula editors (condition/switch) are Monaco: right-click → Snippets inserts ready-made blocks (CRUD, notifications, email, skeletons), including the payload of a graph node picked by name — the id is filled in automatically. For CRUD use wtoolbox.dataService.update/insert/delete(entity[, pristine], datasource): with scope = datasource the provider and the workflow routeContext are resolved automatically (manual AsmxProxy only for routes other than the current step).
Payload in condition and switch expressions
The guard expressions of Condition and Switch nodes also have in scope, besides record (the current row), the `payload` variable: the value produced by the previous action in the chain. To make it available, the callback passes it as the third argument of navigateToNextStep (typically the same value later handed to resolve):
// action callback: the graph picks the branch, based on record AND payload
const esito = await wtoolbox.dataService.update(entity, row, datasource);
wtoolbox.navigateToNextStep(record, null, esito);
resolve(esito);- Condition:
payload.stato === 'approvato'— or mixed expressions such asrecord.totale > 1000 && payload.ok. - Switch: the formula can use both (
return payload.score), and so can the case conditions (resultExpression > payload.soglia). - Note on the pre-click gate: guards are also evaluated BEFORE the action runs (to immediately block a disallowed navigation); at that point the payload does not exist yet, so expressions referencing
payloadare deferred — they do not count at the gate and are applied when the branch is chosen innavigateToNextStep. - Return value of
navigateToNextStep:trueif it started the navigation,falseif the action has no links in the graph (the callback can handle a fallback),'blocked'if links exist but no branch can be taken (guards or permissions not satisfied): the user sees a warning with the failed guard and nothing is navigated.'blocked'is truthy, so a fallback written asif (!wtoolbox.navigateToNextStep(...))does not fire when the graph blocked.
Driving the designer from chat (assistant)
The RAG assistant (the floating button on every page) can create and edit the graph from a natural-language prompt, as it already does for the dashboard designer and the 3D scene. Examples: "build an approval skeleton on the cities route", "add a condition node after the cities route", "insert an action between the route and the end", "configure the switch formula". The assistant proposes a structured action; the Apply chip runs it on the canvas — nothing is persisted until you save the graph. It covers adding every node type, inserting at intermediate points, configuring nodes (condition/switch/timer/callback), removal and connections. Route names come from the app's real routes.
Versioning
- Save version creates a snapshot; History reopens a previous version. The designer title shows the current version.
Runtime (workflow runner)
The runner executes the graph step by step and applies the configured behavior:
- Instance timeline: record state transitions are logged and shown as a history.
- Timer / SLA: timer nodes generate reminders or escalations on the scheduler.
- Assignees: assignee resolution from hierarchy/field and delegation.
- Parallel tasks (split/join): task materialization and continuation once all are complete.
- Email: sending (or queueing) notifications from process steps.
- Menu badges: the runner menu entry can show a counter (e.g. queued items).
Client/Server Integration
- Client:
- graph drawing, canvas interactions, node and transition configuration;
- graph validation and assisted authoring.
- Server:
- persistence of the workflow structure and executive metadata;
- runtime execution of the graph through the workflow runner.
Operational Notes
- Keep node naming semantic and stable for debugging.
- Use "Validate graph" before publishing: it prevents orphan branches, empty conditions and incomplete configurations.
- Verify the runner after every significant structural change.
Screenshot

