Skip to content

Workflow Branching Design

Ed Mozley edited this page Nov 20, 2026 · 2 revisions

Workflow branching - If / Otherwise and Choose by value

GitHub #364, asked for by @duongtuanan Β· 5.8.0 Β· user page: Workflows - Branches Β· internals: Developer Guide 1: the engine Β· 2: the canvas editor Β· 3: safety, saving and tests

The ask

Assign tickets by the requester's email domain: abc.com to Team A, xyz.com to Team B.

The reporter offered two answers: let contains take several values, or add IF / ELSE IF / ELSE branching to the engine, which they preferred. The small answer fixes their example; the big one fixes the whole class of "different actions for different situations" - which until now meant one workflow per situation, with conditions copied between them and nothing to catch the case nobody wrote a workflow for.

Decided

  • 2026-11-20 (Ed): build branching, not just "contains any". Two kinds: If / Else if / Otherwise, and Choose by value - the workflow equivalent of a switch / select case.
  • 2026-11-20 (Ed): every branch always has an Otherwise / Default path, so an unexpected input can never break a run or vanish. It cannot be removed.
  • 2026-11-20 (Ed): built on the test install first; nothing reaches a real install until it has been seen working there.
  • 2026-11-20 (proposed, accepted with the go-ahead): a branch inside a branch is allowed, three deep at most; Choose offers the same fields as conditions, with the same dropdowns for fixed lists and contains for text; an empty Otherwise / Default still shows in the run history as taken.
  • Not in this release: branches in a form's "when submitted" actions (the engine runs them, the form editor does not offer them); the AI co-author writing branches; per-trigger defaults ({{task.ticket_id}} and the like) being re-applied to actions inside a branch when the trigger changes.

The shape

A branch is an entry in the same actions list as any action, so a workflow without one is stored exactly as before:

{ "type": "branch_switch", "args": {
    "field": "ticket.requester_email", "compare": "contains",
    "cases":   [ { "label": "ABC Ltd", "values": ["abc.com"], "actions": [ ... ] } ],
    "default": { "actions": [ ... ] } } }

{ "type": "branch_if", "args": {
    "branches":  [ { "label": "Urgent", "match": "any",
                     "conditions": [ { "field": "ticket.subject", "op": "contains", "value": "urgent" } ],
                     "actions": [ ... ] } ],
    "otherwise": { "actions": [ ... ] } } }

branch_if and branch_switch are not in the action catalogue, so they never appear in the action-type dropdown, the REST API's /workflow-actions or the AI's list.

How a run treats it

  • The first branch / case that matches runs; none matching runs Otherwise / Default. A missing or empty field on a Choose goes straight to Default, with the reason logged.
  • The decision is read-only, so a dry run decides for real and previews only that path's actions.
  • A failing action inside a path fails the run and stops it, exactly as at the top level.
  • Results carry on: after a branch, {{last}} and the branch's own {{steps.N}} hold what the path that ran produced last. Inside a path only {{last}} moves - see the trap below.

Safety: everything that reads an action list

Nothing already built may change, so every reader of workflows.actions was found and taught about branches:

Reader Change
The engine's action loop Runs a branch through executeBranch(); plain actions unchanged
api/workflow/save.php, REST POST/PATCH /workflows validateActionTree() at every depth, then normaliseActionTree() (adds a missing Otherwise / Default)
Webhook credential encryption Was top-level only. A webhook in a branch would have been stored in plain text - and worse, the editor would receive it still encrypted and the next save would encrypt it again. webhookMapWebhooks() now walks every depth
api/workflow/get.php (the editor's copy) Decrypts (or hides) webhooks at every depth, for the same reason
Switched-off-module check Applies inside paths automatically - same loop
Execution log, editor's recent runs Draw the decision and the path's steps beneath

Proved unchanged: every workflow template (27) and the test install's own workflow were dry-run through the old engine and the new one with the same payload; the results were identical, byte for byte (22 action previews, 13 condition checks).

Tests

tests/workflow-branching.php - 38 checks: each path for If and Choose (all / any, equals / contains, several values), Default on no match and on a missing field, Default always added, results after a branch, nesting (two deep runs, four deep refused), dry run, failure, validation messages, webhooks encrypted inside a branch and back, and a branch-free workflow as the positive control. Dropping the guard that keeps nested results out of the top-level steps fails it.

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally