Folder: workflow/ Theme colour: Amber #f59e0b DB tables: workflows, workflow_executions, webhook_deliveries

Cross-module automation engine. Other modules fire events when things happen ("a ticket was just created", "a priority just changed"); the Workflows module listens for those events, evaluates user-defined conditions against the event's payload, and runs an ordered list of actions when the conditions pass. The strategic answer to "why pick FreeITSM over Halo / ServiceNow" on the automation axis.

A workflow has three parts: a single trigger (the event), zero or more conditions (filters, AND semantics), and one or more actions (what to do).

The most common question, and the one it's easiest to get a wrong mental model of. There are three different cases, and they behave differently.

Making a ticket P1 fires the workflow immediately. Nothing polls. Nothing checks on a timer.

When a ticket is saved, the code that writes it calls WorkflowEngine::dispatch('ticket.priority_changed', …) in the same request, synchronously. The engine finds the active workflows for that event, evaluates their conditions, and runs their actions — all before the browser gets its response back. It's a phone call, not a letter.

That's why every trigger in the catalogue hangs off a write path: something has to happen for an event to exist. No scheduled task is involved, and none is needed.

Here's the part that catches people.

The send_webhook action does not POST to Slack or Discord. It queues the message into webhook_deliveries and returns instantly. A background worker — cron/webhook_deliveries.php — does the actual sending, with retries and backoff.

That's deliberate and it's the right design: if Discord is down or slow, your ticket still saves instantly. Nobody should wait on someone else's outage to file a ticket.

But it means the worker has to be scheduled, or nothing ever leaves the building. A workflow will fire perfectly, queue its message, and the message will sit there forever.

The trap. The editor's Send test button is synchronous — it bypasses the queue deliberately, so you get an immediate answer. So Send test can work perfectly while every real webhook silently piles up unsent. If your test posts to Discord but your live P1 doesn't, this is why.

System → Webhooks shows a red banner when the worker isn't running, with the exact command to schedule. Set it to run every minute. Setup: docs/webhook-cron-setup.md.

"The SLA is about to breach." "This contract expires in 30 days."

These are not events. Nothing happened — time passed. There's no write to hang a dispatch() off, so a scheduled job has to go and find them.

Four triggers work this way: sla.warning, sla.breached, contract.expiring, asset.warranty_expiring.

⚠️ If the crons aren't scheduled, these triggers never fire. The workflow sits there, active, doing nothing, and nothing tells you why. See Time-based triggers below.

Seven triggers — sla.warning, sla.breached, contract.expiring, asset.warranty_expiring, project.stage_due, project.milestone_due and project.milestone_missed — don't hang off a write path. Nothing happened; time passed. A scheduled job has to go looking for them, and once it does, the hard part isn't finding a breached SLA — it's not telling you about it 300 times, because a time-based condition stays true.

A fire-once ledger (workflow_scheduled_emissions, unique key + INSERT IGNORE) makes the database the arbiter, and a fingerprint of the state it fired against lets a situation re-arm when the thing underneath it changes — so raising a ticket's priority, which shrinks its SLA target, is allowed to escalate again against the new deadline.

⚠️ These seven need crons scheduled, or they never fire at all — the workflow sits there, active, doing nothing, and nothing tells you why.

📖 Full write-up: Time-Based Triggers — the triggers and their crons, the ledger, the fingerprint, the four starter recipes, cron setup, and how to test the whole thing by hand without waiting for a scheduler.

A few catalogue details worth knowing beyond the event catalogue itself: UI settings endpoints emit their CRUD events via a best-effort wf_emit() helper, while shared services call the engine directly; task.completed fires only on the transition into a closed status (not on every save of an already-closed task); software.application_discovered fires from all three agent-ingest paths when a new application first appears; and form.submitted's payload includes a submission.fields map of every answer keyed by its label, plus the first email-type answer as submission.email.

Catalogue requests add three more form-shaped triggers: catalogue_request.submitted (a gated form was submitted and is waiting on its approver or approving team - it carries approver.id or, since 4.3.0, approval_team.id and approval_team.approvals_required - a gated submission fires this instead of form.submitted, so an auto-raise rule can't jump the approval gate), catalogue_request.approved and catalogue_request.rejected. All three carry form.id, so a rule narrows to one catalogue item rather than every form on the install, and all three carry the same submission.fields map — the four form-shaped triggers share one SUBMISSION_FIELD_TRIGGERS const precisely so that {{submission.fields.Start date}} cannot mean one thing at submission and nothing at approval. The decision events additionally carry request.comment and, on approval, request.ticket_id / request.ticket_number. For a team request they fire once, when the request is decided, not on each vote.

⚠️ A broken lookup is indistinguishable from a missing one. form.id had an entry in FIELD_LOOKUP_TABLES all along, reading a column called name — the forms table has title. The query threw, availableValuesForField() caught it and returned null, and the editor drew an empty tick-list. So "match on this form" was offered and could never be filled in, and the only rule anyone could save ran for every form on the install. Worth a periodic sweep: exercise every entry in that map against the database, because the catch means nothing else ever will. All 29 pass as of #95.

⚠️ The dropdown lists leaves only. Editing a form forks it into a new row and the frozen versions keep their titles, so listing every row offers the same name several times with no way to tell which is current. ⚠️ It follows that a condition pinned to form.id stops matching once that form is versioned — the submission carries the new leaf's id. That trap is one of the reasons a form's own action list belongs on the form (see the Catalogue Request Approvals developer guide), where versioning carries it forward instead.

⚠️ These three were dispatched from the day approvals shipped but never catalogued, so for their whole life they matched zero workflows and the approver was never told anything was waiting. dispatch() selects on trigger_event and the editor can only offer what availableTriggers() lists — so a dispatch() call without a catalogue entry is an event that can never be heard, and nothing anywhere reports the mismatch. Worth checking whenever a new event is added. See the Catalogue Request Approvals developer guide.

Conditions and actions are stored as JSON-in-TEXT columns on the workflows table — so the schema doesn't need a migration every time the engine grows a new operator or action kind.

Process Mapper-style canvas with a dot-grid background, 20px snap-to-grid, and auto-routed SVG connectors. Three node shapes:

• Trigger node — amber pill, pinned to top-centre. One per workflow; can't be deleted.
• Condition node — orange diamond (clip-path).
• Action node — blue rounded rectangle.

Position IS the order. Execution flow at save time is trigger → conditions (sorted top-to-bottom by y) → actions (sorted top-to-bottom by y). Drag a condition above another to swap them. No branching in v1 — purely linear visual.

The toolbar has Back / Add condition / Add action / Status pip (idle / unsaved / saving / saved) / Test fire / Save / AI co-author.

The detail panel slides in from the right with four bodies swapped by selection:

Right-click or Delete removes the selected node (except the trigger). Same mouseup-no-drag pattern Process Mapper landed in #335 so a drag never flashes the detail panel in.

The condition value control adapts to the chosen field type — driven by two const maps on WorkflowEngine:

• FIELD_LOOKUP_TABLES — normalised id fields (ticket.priority_id, ticket.status_id, etc.) get a checkbox list of real values from the joined table. Multi-tick gives OR semantics — "priority is Critical OR High" is one condition with op: in, value: ["4", "3"] rather than two AND-ed conditions which doesn't actually express OR.
• FIELD_TYPES — drives operator filtering. Numeric fields offer equals / not_equals / in / not_in / gt / lt / is_empty / is_not_empty (no contains — substring search on a number is meaningless). Text fields offer the same minus gt / lt (lexicographic string compare is a footgun) plus contains / not_contains, which ignore capitals and the spaces around the typed value (textContains(), #214). Lookup fields collapse to is / is not / is empty / is not empty — the multi-select handles the rest.

The editor's field dropdown is populated from WorkflowEngine::availableFields($trigger) — every ticket.* trigger exposes the full ticket field set (id / subject / priority_id / status_id / department_id / type_id / assigned_analyst_id / owner_id / origin_id / created_by / requester_email / category_id) plus event-specific extras (old_status_id / new_status_id / old_priority_id / new_priority_id / old_category_id / new_category_id / analyst_id / team_id).

Category (ticket.category_id) is a condition on every ticket trigger, so "a new ticket in Hardware" is one condition on A ticket is created. It works on triggers whose event never mentioned a category too (a reply received, a note added, an SLA warning): the engine looks the ticket's category up when the event does not carry it.

Tickets that arrive by email usually have no category until someone triages them, so a second trigger catches that moment: A ticket's category changes (ticket.category_changed). It fires when someone sets, changes or clears a ticket's category - from the reading pane, the workspace, the REST API or another workflow - and not when the same category is saved again. Its event carries old_category_id and new_category_id as well as the whole ticket.

Subcategories. Ticking a category in a condition also matches everything beneath it, so a workflow for Hardware runs for a ticket in Hardware → Laptop (and Hardware → Laptop → Battery). That is the default. An install that would rather name every subcategory it wants sets Tickets → Settings → Categories → Categories in workflows to It matches that category only. The setting is install-wide and applies to every workflow at once; the editor shows a tip under a category condition saying which way it is set, with a link to change it. When a match included subcategories, the run history's condition step says so (includes_subcategories).

1. Workflows → New workflow, name it Hardware to Desktop.
2. Trigger: A ticket is created.
3. Condition: field Ticket · Category, tick Hardware. With the default setting this also catches Hardware → Laptop, Hardware → Printer and the rest.
4. Action: Assign ticket to team, team Desktop. Leave the ticket id as {{ticket.id}}.
5. Save, and use Dry run against a Hardware ticket to see the condition pass.

That routes tickets raised with a category - the portal, the New ticket form, the REST API. For email tickets categorised at triage, make a second workflow the same way with the trigger A ticket's category changes. A ticket created in Hardware and later moved to another Hardware subcategory runs the second workflow as well - harmless for an assignment, but worth knowing before adding a note or email action.

Changing the type. Changing a ticket's type clears a category that belonged to the old type (see Ticket categories). Since 5.1.0 that clearing fires A ticket's category changes too, with the old category and no new one - so a workflow can catch a ticket leaving a category: condition Old category (old_category_id), tick it. Old category and New category are category pick-lists with full paths, like Ticket · Category, and follow the same subcategory setting. The merge codes {{old_category_name}} and {{new_category_name}} give their names.

Developers: Workflow category routing - Developer Guide.

Twenty-two handlers ship today - the eighteen below, plus attach_checklist, escalate_to_tracker, send_note_to_tracker and open_jml_case (Starters & leavers) (see the workflow engine developer guide for all of them and what each returns). Each action's args spec drives the editor UI dynamically — the user gets a labelled form with the right widget per arg (text input / textarea / number / checkbox / lookup <select>), not a JSON textarea.

Attach SOP Checklist(s) (attach_checklist) offers only checklists that apply to tickets (or to both) - a checklist made for tasks only cannot go on a ticket. A workflow saved before one of its checklists was changed to tasks only keeps working: that checklist is skipped, the others are attached, the actions after it still run, and the step leaves a note saying which checklist was skipped and what to change (see Runs that need a look below). Until 5.0.0 the same situation failed the whole run and stopped every action after it.

Action lookups (status / priority / analyst / department / ticket_type / task_status / task_priority) reuse FIELD_LOOKUP_TABLES via the ACTION_ARG_LOOKUPS map and availableActionLookup($key) so action dropdowns and condition value dropdowns share one source of truth.

Every task trigger carries the ticket the task belongs to, as task.ticket_id - a condition field (Task · Ticket) and a merge code - with {{task.ticket_number}}, {{task.ticket_subject}} and {{task.ticket_url}} beside it.

• A ticket action added to a task workflow starts with {{task.ticket_id}} instead of {{ticket.id}}, so "when a task is done, add a note to its ticket" needs nothing typed. Change the trigger and a starting value follows it; a value you typed is left alone.
• Add the condition Task · Ticket is not empty so the rule skips tasks that have no ticket. Without it, a ticket action on such a task fails with "This task is not linked to a ticket" rather than a puzzling "ticket_id is required".
• The ticket actions keep their company check: a company's own workflow cannot reach another company's ticket through a task.
• The recipe When a task is done, note it on its ticket (category Tasks) is the example from the issue, ready to switch on.
• Developers: Workflows for tasks - Developer Guide.
• Loops are stopped by the engine: a workflow on task.status_changed that sets a task status, or on task.comment_added that adds a comment, is refused re-entry.

A webhook is FreeITSM making other systems do things: when a rule fires, it POSTs to a URL you provide. FreeITSM stays deliberately ignorant of the target — the receiving system publishes an "incoming webhook URL," you paste it in, and (for anything beyond the presets) you shape the payload to match what that system expects. This is why one action reaches thousands of tools without a per-integration build.

Slack / Teams / Discord (preset). In the target app, create an Incoming Webhook and copy its URL. In the workflow, add Send a webhook, set Format to the platform, paste the URL, and write the Message (templated, e.g. P1 raised: {{ticket.subject}} (#{{ticket.id}})). FreeITSM wraps it in the platform's shape — Slack {"text": …}, Discord {"content": …}, Teams a MessageCard.

Microsoft Teams, today. Microsoft switched the Office 365 connector webhooks off in May 2026. In Teams, a channel's address now comes from Workflows → "Post to a channel when a webhook request is received", and the format to choose is Microsoft Teams (Workflows card) - an Adaptive Card with an Open in FreeITSM button on {{link}}. Microsoft Teams alerts builds these workflows from a page of ticks.

Anything else (Custom). Set Format to Custom (raw JSON body) and write the exact JSON the target wants, with {{variables}} filled in. For maximum reach, point it at a Zapier / Make / n8n webhook and let that fan out to any app.

Full-record loading under the hood. The full-object enrichment is a registry of loaders keyed by payload object — WorkflowEngine::fullObjectLoaders() — one per resource with a clean API GET /{id}. Each loader runs the resource's own raw SELECT + serialiser rather than the apiLoadX() helpers, because those apiError()/exit on a missing row and would abort the host module's request. Loading is best-effort as well as lazy: if a load fails, .full is simply omitted rather than failing the run.

Verifying authenticity (signing secret). Set a secret and FreeITSM adds X-FreeITSM-Signature: sha256=<hex>, where the hex is HMAC-SHA256(raw_body, secret). The receiver recomputes the HMAC over the exact bytes received and compares — a match proves the call came from your install and wasn't tampered with. (PHP receiver: hash_equals('sha256='.hash_hmac('sha256', file_get_contents('php://input'), $secret), $_SERVER['HTTP_X_FREEITSM_SIGNATURE']).)

A blank canvas is a bad first experience. New from template on the Workflows list opens a gallery of 27 ready-made recipes for the jobs most service desks automate first, across 15 categories — filterable by category and searchable (the search reaches the description, trigger and actions too, so expiry, slack or wipe find the right card even when the name doesn't contain the word).

Tickets and incidents: auto-acknowledge a new ticket, thank the requester when it closes, P1 incident response, alert when a ticket is escalated to P1 (the case a create-time rule misses), broadcast a status-page incident, sound the all-clear when it's resolved (teams remember the outage and never hear it ended), log every ticket that's binned. Onboarding: new-starter form → IT + HR + Facilities tickets + a task to chase them. Change: flag a high-risk change for CAB review, raise an implementation task when one is approved. Assets: chase the acceptable-use paperwork when kit is issued, wipe-and-restock when it comes back. Tasks: when a task is done, note it on its ticket (#274). Also: root-cause investigation on a new problem, supplier due diligence, contract setup, a ticket when a morning check fails, a shadow-IT alert on newly discovered software, an alert when a CI is deleted, an orphaned-link check when an article is archived, and announcing a published article.

Four are time-based — the recipes that were impossible before the scheduled triggers landed:

⚠️ These four need the crons scheduled — see Time-based triggers. Without them the workflow sits there, active, and never fires. The two expiry recipes fire at 90 / 30 / 7 / 1 days out and each ships filtered to the 30-day window (window_days equals 30); change or drop that condition to be told at every window.

Pick one and it's copied in as a normal, fully editable workflow. There's nothing special about it afterwards — rename it, rewire it, delete it.

Action args like status_id are numeric IDs that differ per install. A recipe cannot hardcode status_id: 5 — your "Closed" might be 5, mine might be 9, and someone else calls it "Done".

So a template declares its lookups by name, and the resolver maps them to this install's real IDs at clone time:

'value' => ['$lookup' => 'ticket_status', 'names' => ['Closed', 'Resolved', 'Complete', 'Done']],

Candidate names are tried in order, so a desk with both Critical and High correctly gets Critical for P1. Values only the user can supply (a Slack webhook URL) use a ['$configure' => '…'] marker instead.

Anything that can't be resolved is cloned blank and reported in an unresolved list, which the editor renders as a "these fields still need you" banner. A recipe always clones — it just tells you honestly what it couldn't fill in, rather than silently half-working.

Cloned workflows arrive inactive. Nothing a recipe contains can fire until it's been read, filled in and switched on.

Every template's trigger and action types are checked against the live engine catalogues — a recipe that couldn't actually run would be worse than no recipe.

Key file: workflow/includes/templates.php

Until #95 every action ran in the dark. runInner() put each result into the execution row's step_log and nowhere else, so a workflow could create a ticket and its very next action had no way to name it. "Raise a ticket, then email the requester about it" was unbuildable — and unbuildable as two workflows too, because create_ticket dispatches no event of its own.

A successful action's result is now merged back into the payload under two names:

last covers the common two-action chain; steps is what a third action needs, because by then last is the second action's result.

🔑 Merged under their OWN keys, never into the payload's natural namespace. Writing a new ticket's id over ticket.id would silently repoint every later {{ticket.*}} on a ticket-triggered workflow at a different ticket from the one that fired it — a workflow that had been correct for a year would quietly start emailing about the wrong record.

⚠️ steps is one-based, matching the number the editor prints next to each action. A merge code that disagreed with the number on screen would be wrong in the one place people copy it from.

⚠️ Nothing is merged on a dry run (nothing ran, so a later action's preview shows the merge code unresolved — which is honest) or after a failed action (the chain stops there anyway).

Both prefixes are returned by variablePrefixes() for every trigger, since what an earlier action produced depends on the actions chosen, not on what fired the workflow.

FreeITSM had two implementations of "turn a form submission into a ticket", and they disagreed:

So the configurable path produced the worse ticket. action_create_ticket() now delegates to the shared path whenever the payload carries a submission.id, with the configured args applied on top as overrides.

🔑 The rule is: an override always wins, and the submission fills in whatever was left blank. That single sentence is what lets one function serve the approval path (which configures nothing) and a form's own action list (which may configure everything).

⚠️ A blank body now means "show me what they asked for" — the escaped answer table — rather than an empty ticket. That is a behaviour change for any existing form.submitted workflow that left the body empty, and a strict improvement.

⚠️ The engine must lazily require_once includes/catalogue_approvals.php inside the handler. Both that file and includes/services/forms.php require the engine at file level, so a top-level require back would be circular. Same idiom as the notifications router and the search indexer.

Anything with no submission in its payload — a fan-out from ticket.created, say — keeps the original behaviour untouched.

send_email took its mailbox from the ticket, so it could not acknowledge anything that was not yet a ticket. It now takes either a ticket or a mailbox_id, with an explicitly chosen mailbox winning over the ticket's own.

⚠️ No ticket means no reply marker. buildTemplateEmailBody() appends "please reply above this line" over an [*** SDREF:… ***] token, which is what threads a reply back onto the ticket. With no ticket the token is empty, so the trailer would invite a reply that lands nowhere — a standalone send uses plainEmailBody(), which is the same styling without the marker.

⚠️ templateSaveSentEmail() is skipped without a ticket (there is no conversation to file the copy against), but emailLogSent() still records the send, so a standalone message is auditable in Email send log — it just isn't attached to anything.

mailbox is an action lookup only, never a condition field: nothing dispatches a mailbox id in a payload, so there would be nothing to compare against.

Dry run (toolbar, beside Test fire) evaluates the workflow's conditions for real, then describes each action instead of executing it.

The run is logged like any other but flagged is_dry_run, and each step records would_run (the action's catalogue label) plus would_args — the args with {{variables}} already substituted. So you read the actual email subject, the actual chat message, the actual note. Not the template: the finished text.

Nothing is written, emailed, queued or sent — no ticket mutations, no notes, no webhook_deliveries rows — and the workflow's run_count / last_run_datetime are untouched. A dry run is not a run. Any signing secret is redacted rather than echoed back, so the debugging surface can't be used to read a secret out of a saved workflow.

That makes it safe to point at a live workflow, and it's the sensible first thing to do with a freshly cloned template.

Dry run vs Test fire. Test fire actually executes — it will genuinely send that email. Dry run won't. The help page separates them explicitly, because the distinction matters the first time you point one at production.

Any free-text action arg supports {{path.to.field}} placeholders, resolved against the dispatch payload at execution time via the engine's renderTemplate() helper.

You don't type them by hand. Every variable-friendly field has an Edit with variables button that opens a roomy editor with a searchable variable list beside it — click one and it drops in at the cursor. A live preview shows the finished text with each code swapped for what it stands for.

renderTemplate() resolves an unknown path to an empty string. It does not error.

So a workflow on knowledge.published whose message says {{ticket.subject}} doesn't fail — it quietly posts a blank where the subject should be, and nobody notices. There is no ticket in a knowledge event.

WorkflowEngine::availableVariables($trigger) is the catalogue of codes a given trigger can actually resolve. The picker offers only those, and a hand-typed code that can't resolve is flagged under the field ("will come out blank — not available on this trigger").

This catalogue is deliberately distinct from availableFields(), which answers a different question — "what can I write a condition on" (scalars only). {{event}} is a valid merge code and a useless condition field; {{ticket.full}} is a whole JSON object, meaningless in a comparison.

{{ticket.priority_id}} renders as 4. That's fine for a receiving system that expects an id, and useless in a message a person reads — nobody in your Slack channel knows what priority 4 is.

So every lookup field has a readable twin:

The picker gives the name the plain label (Ticket · Priority) and marks the numeric one (id). Labelling them the other way round would hand the natural-sounding name to the field that renders a meaningless number.

The twins are derived from the same FIELD_LOOKUP_TABLES registry that powers the condition dropdowns — so adding a new lookup field gets you its name code for free, with no second list to maintain. That includes {{old_priority_name}} / {{new_priority_name}} on the change triggers, so "escalated from High to Critical" writes itself.

Resolution happens once per run (enrichWithLookupNames(), cached), before conditions and actions — so the step log, the dry-run preview and every action all see the same enriched payload. It never clobbers a value the host module set deliberately: form.submitted already ships a real form.name, and that wins over anything derived from form.id.

Same idea, one level up. {{ticket.id}} is the internal database id (83). The thing a requester quotes back at you — and the thing that belongs in an email subject or a chat alert — is the ticket number (ETC-623-64409).

Also {{problem.number}}. Changes and tasks have no reference column, so they're correctly offered none — their id is their identity today.

Named number, not "ref": the app and the schema already call it a number (tickets.ticket_number), and a third word for the same concept is just a synonym to learn.

⚠️ One exception, and it matters. A Ticket ID action argument must stay {{ticket.id}}. That field tells the engine which record to act on, and it looks it up by row id — feed it a ticket number and the action fails. The rule: the number goes in the words a person reads; the id stays in the plumbing. The starter templates follow exactly this split.

It also offers:

• {{event}} — the name of the trigger that fired.
• {{link}} — the page the event is about, as a full address: the ticket when there is one, otherwise FreeITSM's front page. Never empty, so it is safe as a chat card's button. Also {{ticket.url}} (that ticket) and {{app.url}} (the front page). Built from the public base URL by enrichWithLinks().
• {{<object>.full}} — e.g. {{ticket.full}}, the entire record as JSON, in the exact shape the REST API returns it (for objects the engine can hydrate whole). Any field of it works by path, in every action (#275): {{task.full.ticket_id}} is the ticket a task is linked to, {{ticket.full.requester.email}} the requester's address. Before #275 .full was only loaded for Send webhook, so these were blank anywhere else. It is loaded only when an action uses .full, and never for a confidential ticket - the same rule the webhook follows.
• {{submission.fields.<your form's label>}} — an open-ended shape for form answers, which can't be enumerated because they're keyed by whatever the form author called them.

Labels are derived from the path (ticket.requester_email → "Ticket · Requester email") rather than hand-mapped, so they can't rot as the 138-trigger catalogue grows.

See Workflow & Webhook Pitfalls #1 and #2 — the send_webhook action's own default body template shipped referencing {{event}}, which the engine never populated, so every custom webhook built from the default had been sending "event": "". That bug was found by building this picker.

Common variables for ticket triggers:

• {{ticket.id}}, {{ticket.subject}}, {{ticket.priority_id}}, {{ticket.status_id}}
• {{ticket.department_id}}, {{ticket.type_id}}, {{ticket.assigned_analyst_id}}
• {{ticket.owner_id}}, {{ticket.created_by}}, {{ticket.requester_email}}
• For ticket.status_changed / ticket.priority_changed: also {{old_status_id}}, {{new_status_id}}, {{old_priority_id}}, {{new_priority_id}}
• For ticket.assigned: also {{analyst_id}}, {{team_id}}
• For ticket.created: also {{ticket.assigned_team_id}} / {{ticket.assigned_team_name}} — the team it arrived with
• For ticket.team_assigned: also {{team_id}} / {{team_name}} — the team it was handed to. ⚠️ Not ticket.assigned_team_id: this event does not carry it, and a condition on it never matches.

In ticket_id fields, the default {{ticket.id}} is pre-filled — leave it as-is so the workflow operates on whichever ticket triggered it. Specifying a literal id hard-codes the workflow to one ticket.

Key methods: WorkflowEngine::availableVariables($trigger) (the merge-code catalogue), variablePrefixes($trigger) (open-ended shapes like submission.fields.).

Toolbar button (amber-tinted, sparkle icon) opens a modal where the user describes the workflow in plain English. The backend (api/workflow/_ai_helpers.php + api/workflow/ai_compose.php) sends a system prompt that contains the live engine catalogues — every trigger, condition operator, action, and the per-action arg schemas with the first 8 id=label pairs of every lookup table — so the AI can only propose things the engine actually understands.

The model returns a JSON proposal that's validated server-side against the same catalogues. Unknown triggers fall back to the first known one, unknown operators / actions are dropped with warnings surfaced to the client. The modal shows the AI's explanation, a colour-coded preview of the proposed workflow, any warnings. Apply replaces the canvas nodes with the proposal; Discard lets the user try again. When the canvas already has content, the AI iterates on it — "now only match Finance" / "add an action to log the ticket id too" edits what's there rather than starting over.

Provider-aware — works with both Anthropic and OpenAI (and falls back to either if you have one of them configured). Settings page at workflow/settings/ lets you pick the provider, model, API key (encrypted, masked) and verify-SSL toggle per module, so installs can route different modules' AI calls to different accounts for granular billing.

4.1.0 (#209). Only on an install with more than one company - with one, nothing here appears and nothing changes.

Every workflow is either shared or one company's own, chosen under Runs for in the editor.

The list follows the company switcher: the shared workflows plus those of the company you are in. An event that belongs to no company - a supplier being saved, a status renamed - runs only the shared workflows.

The run log follows the event. Each run is filed under the company its event belonged to and shown only to people who can see that company. A run with no company (a settings event, or a run from before 4.1.0) is shown to people who can see every company.

A shared workflow can still treat companies differently. Every trigger gains a Company condition field and {{company.id}} / {{company.name}} merge codes. But a condition is not a boundary: anyone who can edit the workflow can change it. To keep a workflow to one company, set Runs for.

Created records follow the company too: a ticket or task raised by a company's workflow is that company's, and a task a shared workflow links to a ticket takes the ticket's company (before 4.1.0 every workflow task landed in the Default company). How it is built: Workflow engine - Developer Guide.

The Test fire button runs the workflow with a synthetic payload built from its own conditions — the editor sets payload[field] = condition.value for each equality op (or sentinels for is_empty etc.), so the conditions trivially pass and the action path actually executes. The result lands in Recent runs on the workflow detail panel with status (success / failed / skipped) and full step log.

To test against real data, just do the thing that triggers the workflow — assign a ticket, change its priority, etc.

A test fire is logged as a normal execution, but it doesn't increment the workflow's run_count counter — so the production metrics stay clean however many times you test.

The engine deliberately swallows its own errors. A broken workflow must never break the ticket save that triggered it, so dispatch() catches everything and writes it to the execution row rather than letting it propagate.

That is the right call. It also means a workflow can fail on every single fire and nothing anywhere tells you.

Two things break that silence.

Every run of every workflow. Before this, the only view of a run was the editor's Recent runs panel — the last 20 runs of one workflow, no filters, no search, no history. That's the wrong shape for the question you actually ask when something breaks ("what failed, and why?"), because you don't yet know which workflow to open.

• Filter by workflow, status, trigger, date range, dry-run vs real, or free text over the workflow name / trigger / error message.
• Status tallies double as one-click filters — the failure count is also the button that shows you the failures.
• Filters live in the URL, so a view is bookmarkable and shareable. That's what lets the Watchtower card link straight to today's failures instead of dropping you at an unfiltered list.

Open a run and you get what the engine actually did:

(5.0.0) Sometimes an action can do only part of what it was asked, for a reason somebody should fix - Attach SOP Checklist(s) naming a checklist that is now for tasks only is the first case. The run is not a failure: it succeeds, and the later actions still run. But the step carries a note, shown in amber, saying what was skipped and what to change (Not attached - for tasks only, so it cannot go on a ticket: "New starter kit". Change the workflow, or make the checklist for tickets too.). If the action did nothing at all, the step shows as skipped; if it did some of its job, as success.

To find them, choose Needs a look (an action left a note) in the execution log's status filter (?status=attention in the address). The Watchtower card below counts them too.

Runs stay attributable after their workflow is deleted — the workflow name is snapshotted onto the row (workflow_name), so history survives and remains searchable by name even though workflow_id goes NULL.

The dashboard-level answer to the same problem. Over the last 24 hours:

• Failed runs — the workflow errored.
• Aborted runs — loop protection refused to run it (see Engine internals).
• Dead-lettered webhooks — and this one is easy to miss: the workflow succeeded. It queued the send. The message simply never arrived, after every retry. Nothing else in the product would ever surface that.
• Runs that left a note (5.0.0) - the run succeeded, but an action skipped part of its job (see Runs that need a look above). Shown as "N run(s) skipped part of their job and left a note - latest: Onboarding kit" (the newest such workflow), linking to the execution log filtered to Needs a look.

Red on failures or aborts, amber on dead webhooks or runs that left a note, green when clear. A run that left a note stops the card saying No workflow failures.

It doesn't just count — it names the failing workflows and shows what the error said. "3 failures" sends you hunting; "Unknown status_id: 999999" usually answers the question where you're standing. Every line deep-links into the pre-filtered execution log.

Dry runs are excluded. A dry run is a person testing something, and its failures are expected — not an incident.

Triggers are dispatched from host modules' save flows. The catalogue now spans every module (138+ triggers — see the trigger catalogue notes above and the Webhooks event list): rich domain events like ticket.created, form.submitted, task.completed, change.approved, problem.created, knowledge.published, service_status.incident_created, morning_check.recorded, software.application_discovered and the project events (project.health_changed, project.tolerance_breached, project.stage_closed, project.stage_due, 3.2.0), plus generated .created/.updated/.deleted triggers for every reusable entity and settings lookup. The original four ticket triggers illustrate the wiring pattern:

Each dispatch is wrapped in a defensive try/catch on the host-module side (engine already swallows internally — belt+braces so an engine outage can't break the host module's response that's already been echoed). UI settings endpoints emit via the best-effort wf_emit() helper; shared services call the engine directly.

WorkflowEngine::dispatch($event, $payload)        ← host modules call this
   → SELECT * FROM workflows WHERE trigger_event = ? AND is_active = 1
   → for each matching workflow:
       → insert workflow_executions row (status = 'running')
       → evaluate conditions (AND); if any fail, status = 'skipped'
       → else: foreach action, executeAction(type, args, payload)
           → renderTemplate() resolves {{vars}} in free-text args
           → handler (one of the 8) does the work
           → if it throws, mark step failed, stop the chain
       → update workflow_executions with final status + step_log
       → update workflows.last_run_* + run_count

Failures are isolated. A buggy workflow cannot break the host module's request. Engine-level errors go to PHP error_log; per-action errors go to the execution row's step_log; neither propagates.

Infinite-loop protection. Workflow actions mutate host data that re-dispatches events, so a workflow could trigger itself — directly (A fires an event that re-runs A), via a cycle (A → B → A), or via fan-out. Because execution is synchronous within one request, the engine guards every run with three request-scoped counters: an active-workflow stack (a workflow already running in the current chain is refused re-entry — catches every cycle), a chain-depth ceiling (MAX_CHAIN_DEPTH, the backstop for deep acyclic cascades), and a per-request run ceiling (MAX_RUNS_PER_REQUEST, the backstop for fan-out). A blocked run is recorded as an aborted execution row with the reason, so the block shows up in the audit — and on the Watchtower card — rather than failing silently.

Actions run synchronously, webhooks do not. Every action runs inside the event that triggered it, so keep actions fast and idempotent - except send_webhook, which queues a delivery that a scheduled worker sends with retries (see Outbound webhooks in practice). Async + retry land when the first slow external action (Microsoft Graph) requires them.

The two main ones below; the engine also uses workflow_scheduled_emissions (time-based triggers), webhook_deliveries (the outbound queue) and webhook_message_formats - all five are in the developer guide.

• Webhooks — done, all phases: the send_webhook action, async delivery (queue, retries/backoff, dead-letter, delivery log with Replay), Send-test button, full-object payloads, the 138-trigger catalogue, and the overview dashboard. See Webhooks.
• Teams / Slack messages — done via the send_webhook action (Slack/Teams/Discord presets).
• Dry-run mode — done. See Dry run above.
• Starter recipes — done. See Starter templates above. (SLA-breach escalation and licence-renewal reminders are not in the shipped set — neither has a wired trigger yet; see below.)
• Tier 3 actions — Microsoft Graph: graph_add_to_group, graph_assign_license, graph_disable_user. The new-starter / leaver automations that justify the module's existence vs paid ITSM suites. Reuses the existing tenant OAuth scaffolding from the mailbox integration.
• SLA + contract-renewal triggers — done. Four time-based triggers (sla.warning, sla.breached, contract.expiring, asset.warranty_expiring), a fire-once ledger, and the four starter templates that were previously impossible. See Time-based triggers above.
• Cross-workflow execution log — done. See The execution log above.
• Watchtower integration — done. Failed runs, loop-protection aborts and dead-lettered webhooks surface as an attention card.
• Workflow versioning — draft / publish / rollback.
• Streaming AI co-author — claude.ai-style live output as the canvas builds.

• 🛠️ Workflow notes on a ticket - Developer Guide
• 🛠️ Workflow category routing - Developer Guide
• Time-Based Triggers — SLA, contract and warranty triggers: the crons they need, the fire-once ledger, and how to add one of your own.
• Webhooks — the outbound-webhook deep dive (formats, signing, delivery engine, data protection).
• HTTPS Certificates & CA Bundles — why unable to get local issuer certificate is almost never your webhook's fault.
• Workflow & Webhook Pitfalls — real bugs found in this code, what caused them, and the general shape of each.