Skip to content

Workflow Branching Developer Guide 3 Safety and Tests

Ed Mozley edited this page Nov 20, 2026 · 1 revision

Workflow branching - Developer Guide, part 3: safety, saving and tests

Part 1: the engine Β· Part 2: the canvas editor Β· Part 3 of 3 Β· Workflow branching - design Β· GH #364

Branching changed the shape of a column that a dozen pieces of code read. This page lists every one of them, shows the two that would have broken quietly, the save-time rules, how "existing workflows are unchanged" was proved rather than assumed, and the tests. If you are about to change anything that reads workflows.actions, read section 1 first.

1. Every reader of an action list

Before writing any engine code, every place that reads or writes workflows.actions (and a form's own action lists, which share the shape) was found with a search for ['actions'], "actions" and actions LIKE. Each had to be one of: taught about branches, safe because it calls the engine, or safe because it only searches text.

Reader Before Now
WorkflowEngine::executeActionList() flat loop branches go to executeBranch(); recursion handles nesting (part 1)
Switched-off module check (GH #217) inside the loop applies inside paths automatically - same loop
api/workflow/save.php each top-level type checked against the catalogue validateActionTree() + normaliseActionTree()
REST POST /workflows, PATCH /workflows/{id} apiValidateWorkflowActions(), catalogue only also accepts BRANCH_TYPES, then the same tree rules
webhookEncryptActions() / webhookDecryptActions() top level only webhookMapWebhooks(), every depth - section 4
api/workflow/get.php (the editor's copy) own top-level loop webhookMapWebhooks() - section 4
Forms' "when submitted" lists (includes/services/forms.php, api/forms/get_form.php) use the webhook helpers fixed by the same helper fix; the form editor does not offer branches
Execution log, editor's Recent runs flat step log recurse through steps (part 2)
Feature Bingo cards, the job registry (actions LIKE '%send_webhook%') text search unchanged and still right - LIKE finds text at any depth
api/workflow/list.php, REST actions_count do not walk actions / count the top level unchanged; a branch counts as one step

2. Proving old workflows unchanged

"It shouldn't change anything" is a claim; this is how it was checked. A script dry-runs every workflow in the test database with a fixed payload, through the engine loaded from a given folder - once from the live code (freeitsm-app, before branching) and once from the new code (freeitsm-prtest) - and writes each run's full result (status, step log, error) to a file:

// br_regress.php <engine-root> <out.json>  - the test install's DATABASE, the given folder's ENGINE
require $root . '/workflow/includes/engine.php';
$payload = ['ticket' => ['id' => 0, 'subject' => 'Printer urgent', 'requester_email' => 'ann@abc.com',
            'priority_id' => 4, 'status_id' => 1, 'category_id' => 1, 'assigned_team_id' => 1], ...];
foreach ($c->query('SELECT id FROM workflows ORDER BY id')->fetchAll(PDO::FETCH_COLUMN) as $id) {
    $r = WorkflowEngine::manualFire((int)$id, $payload, true);   // dry run: nothing written but the run row
    unset($r['execution_id']);
    $out[$id] = $r;
}
$c->exec("DELETE FROM workflow_executions WHERE id > $maxBefore");   // and that row is removed

The workflows compared:

  • all 27 starter templates, created as inactive copies;
  • Ed's 4 real workflows - their definitions read with a SELECT from his install and copied to the test install as inactive rows (nothing written to his install);
  • run twice: as stored, and again with every copy's conditions cleared, so that workflows whose conditions did not match the sample payload still had every action previewed.
Pass Workflows Identical Action previews compared
As stored 32 32 22 + condition checks
Conditions cleared 32 32 42

The only difference in either pass was the branching demo itself, which the old engine cannot run at all (Unknown action type: branch_switch) - as it should. The copies were deleted afterwards.

3. The test file

tests/workflow-branching.php - run from a test install, never a real one:

php tests/workflow-branching.php

It creates ZZ workflows made of Log a message actions whose text names the path, fires them with WorkflowEngine::manualFire(), and reads which messages were logged at any depth:

/** The messages the run logged, in order, at any depth. */
function messages(array $steps): array
{
    $out = [];
    foreach ($steps as $s) {
        if (($s['kind'] ?? '') === 'action' && isset($s['result']['message'])) $out[] = $s['result']['message'];
        if (($s['kind'] ?? '') === 'action' && ($s['status'] ?? '') === 'dry_run') $out[] = 'DRY:' . ($s['would_args']['message'] ?? '');
        if (($s['kind'] ?? '') === 'branch') $out = array_merge($out, messages($s['steps'] ?? []));
    }
    return $out;
}

Fixtures go in through the same validateActionTree() β†’ normaliseActionTree() β†’ webhookEncryptActions() chain save.php uses, and are removed - with their runs - in a finally block. Log a message writes nothing but the run history, so the test touches no tickets.

Section Checks
1. If / Otherwise first matching branch; contains ignores capitals; else-if with any matching on its second condition; nothing matching β†’ Otherwise; every branch tried is logged
2. Choose by value contains (abc.com in ann@abc.com); several values; no match β†’ Default (no_match); missing field β†’ Default (missing), run still succeeds; equals matches number 4 to saved "4"; an empty Default is still logged as taken
3. Default always there a Choose saved without Default gets one; an If without Otherwise gets one; comma-separated values become a list; a list without branches is stored exactly as it was
4. Results after a branch, {{steps.N}} / {{last}} are the path's last result; a nested action never overwrites a top-level step
5. Nesting two deep runs both paths; inner Default; four deep refused with a message; three deep allowed
6. Dry run, failure dry run decides for real, previews only the path; a failing action inside a branch fails the run and stops it
7. Validation no branches, no conditions, no field, an unknown action type inside a path - each refused; plain actions still pass
8. Webhooks a URL inside a case and inside Default is encrypted at rest; decrypts back to exactly what was saved
9. Control a workflow with no branches runs as before, results chained; unmatched conditions still give skipped

38 checks. And the test was itself tested - each guard removed, the suite run, the guard put back:

Removed Result
the $depth === 0 guard round mergeStepResult() 2 checks fail (the nested-overwrite checks)
Otherwise / Default never being taken the run crashes before the summary - caught

The rest of the workflow suite was run against the new code as well: workflow-company-scope (87), workflow-category-routing (24), workflow-task-actions (23), webhook-delivery-settings (23), workflow-attach-checklist-scope (13), workflow-ticket-note (11), form-webhook-full-record (9), workflow-form-fanout (7), workflow-set-ticket-field (7), workflow-full-record (4), workflow-contains - all pass.

The editor was checked by scripts driving a headless browser: load the demo, add a Choose from the toolbar, + Action and + If inside a case, try to delete Default (refused, lane count unchanged), add and remove a case, Save - then read the stored JSON back. A separate round trip loads a branched workflow and saves it untouched; the stored JSON (positions aside) was byte-identical.

4. The two quiet breakages

Webhook credentials

A webhook action's URL and signing secret are encrypted at rest. The helper that did it looked only at the top level:

// before - includes/webhook_delivery.php
function webhookEncryptActions(array $actions): array {
    foreach ($actions as $i => $a) {
        if (!is_array($a) || ($a['type'] ?? '') !== 'send_webhook') continue;
        ...

A webhook inside a branch would therefore have been stored in plain text. Worse, the editor's loader (api/workflow/get.php) had its own top-level-only decrypt loop - so if a nested webhook had been encrypted, the editor would receive it still encrypted, show the ciphertext as the URL, and the next save would encrypt the ciphertext again. The webhook would stop working, silently, the first time anyone saved the workflow.

Both now use one walker:

/**
 * Every send_webhook action in a list through $fn - at ANY depth (GH #364).
 *
 * TRAP: a workflow's actions can hold branches (branch_if / branch_switch) with their own
 * action lists. A walker that looks only at the top level stores a webhook inside a branch
 * in plain text, and - worse - the editor gets it back still encrypted and the next save
 * encrypts it again, so the webhook silently stops working. Self-contained on purpose
 * (this file is loaded without the workflow engine); the shape matches
 * WorkflowEngine::mapActionTree().
 */
function webhookMapWebhooks(array $actions, callable $fn): array {
    foreach ($actions as $i => $a) {
        if (!is_array($a)) continue;
        $type = $a['type'] ?? '';
        if ($type === 'send_webhook') { $actions[$i] = $fn($a); continue; }
        if ($type !== 'branch_if' && $type !== 'branch_switch') continue;
        $args = is_array($a['args'] ?? null) ? $a['args'] : [];
        foreach (['branches', 'cases'] as $listKey) {
            foreach (is_array($args[$listKey] ?? null) ? $args[$listKey] : [] as $j => $path) {
                if (is_array($path['actions'] ?? null)) $args[$listKey][$j]['actions'] = webhookMapWebhooks($path['actions'], $fn);
            }
        }
        foreach (['otherwise', 'default'] as $k) {
            if (is_array($args[$k]['actions'] ?? null)) $args[$k]['actions'] = webhookMapWebhooks($args[$k]['actions'], $fn);
        }
        $actions[$i]['args'] = $args;
    }
    return $actions;
}

function webhookEncryptActions(array $actions): array {
    return webhookMapWebhooks($actions, function (array $a): array {
        foreach (['url', 'secret'] as $k) {
            if (isset($a['args'][$k]) && $a['args'][$k] !== '') $a['args'][$k] = webhookEncrypt((string)$a['args'][$k]);
        }
        return $a;
    });
}
// api/workflow/get.php - the editor's copy, decrypted (or hidden from a reader who cannot edit) at every depth
$canEdit = !empty($wf['can_edit']);
$wf['actions'] = webhookMapWebhooks($wf['actions'], function (array $a) use ($canEdit): array {
    foreach (['url', 'secret'] as $k) {
        if (isset($a['args'][$k]) && $a['args'][$k] !== '') $a['args'][$k] = $canEdit ? webhookDecrypt((string)$a['args'][$k]) : '(hidden)';
    }
    return $a;
});

At run time nothing changed: action_send_webhook() decrypts its own url / secret at the point of use, so an encrypted value works at any depth.

Nested results overwriting top-level ones

{{steps.N}} is written by position, and a position inside a path is not a position in the workflow. See part 1, section 7.

5. Saving: validate, then normalise

Both save routes run the same two calls on the whole tree:

// api/workflow/save.php
// GH #364: at every depth - a branch's paths hold actions too - and every branch gets
// its Otherwise / Default, so an unexpected value always has somewhere to go.
if (($treeError = WorkflowEngine::validateActionTree($actions)) !== null) {
    echo json_encode(['success' => false, 'error' => $treeError]);
    exit;
}
$actions = WorkflowEngine::normaliseActionTree($actions);
// api/v1/resources/workflows.php - apiValidateWorkflowActions()
if (!isset($catalogue[$type]) && !in_array($type, WorkflowEngine::BRANCH_TYPES, true)) {
    apiError(422, 'invalid_field', "actions[{$i}]: unknown action type '{$type}'. See GET /workflow-actions.");
}
...
if (($treeError = WorkflowEngine::validateActionTree($out)) !== null) {
    apiError(422, 'invalid_field', $treeError);
}
return WorkflowEngine::normaliseActionTree($out);

validateActionTree()

Recursive; returns the first problem as a sentence that names where it is, or null:

public static function validateActionTree($actions, int $depth = 0, string $where = 'actions'): ?string
{
    if (!is_array($actions)) return "{$where} must be a list.";
    $catalogue = self::availableActions();
    foreach (array_values($actions) as $i => $a) {
        $at = "{$where}[{$i}]";
        ...
        if (isset($catalogue[$type])) continue;
        if (!in_array($type, self::BRANCH_TYPES, true)) return "Unknown action type: {$type}";
        if ($depth + 1 > self::MAX_BRANCH_DEPTH) return "{$at}: branches can only go " . self::MAX_BRANCH_DEPTH . ' deep.';
        if ($type === 'branch_if') {
            $branches = $args['branches'] ?? null;
            if (!is_array($branches) || !$branches) return "{$at}: an If needs at least one branch.";
            foreach (array_values($branches) as $bi => $br) {
                $n = $bi + 1;
                if (!is_array($br) || !is_array($br['conditions'] ?? null) || !$br['conditions']) return "{$at}: branch {$n} needs at least one condition.";
                foreach ($br['conditions'] as $c) {
                    if (!is_array($c) || trim((string)($c['field'] ?? '')) === '') return "{$at}: branch {$n} has a condition with no field.";
                    if (!isset(self::availableOperators()[(string)($c['op'] ?? 'equals')])) return "{$at}: branch {$n} has an unknown operator.";
                }
                if (($e = self::validateActionTree($br['actions'] ?? [], $depth + 1, "{$at} > branch {$n}")) !== null) return $e;
            }
            if (($e = self::validateActionTree($args['otherwise']['actions'] ?? [], $depth + 1, "{$at} > otherwise")) !== null) return $e;
        } else {
            ...   // a field, at least one case, then each case's and Default's actions
        }
    }
    return null;
}

So an unknown action deep inside a path is refused with its address - e.g. actions[1] > case 2 > .... Over the API:

POST /api/v1/workflows   {"actions":[{"type":"branch_switch","args":{"field":"","cases":[]}}], ...}
422  {"error":{"code":"invalid_field","message":"actions[0]: Choose by value needs a field."}}

Checked over HTTP on the test install with a temporary key: that request got exactly that reply; a valid branched workflow sent with "values": "abc.com, abc.co.uk", no Default and a webhook inside its case was stored with values as a list, an empty Default added, and the webhook URL encrypted.

normaliseActionTree()

Writes back only the keys the engine reads, gives every branch its fallback, turns "a, b" into ["a","b"], and keeps x / y on top-level entries. A plain action passes through untouched ($out[] = $a), which is why a workflow with no branches is stored byte-for-byte as before - a check in the test file.

mapActionTree()

The engine-side twin of webhookMapWebhooks(), for any future code that must touch every plain action at any depth:

$actions = WorkflowEngine::mapActionTree($actions, function (array $action): array {
    // ... change and return it
    return $action;
});

6. Extending it

Adding a third branch type (say, "run every path"): add it to BRANCH_TYPES; teach executeBranch(), validateActionTree(), normaliseActionTree() and mapActionTree() its shape; add its list keys to webhookMapWebhooks() (which deliberately does not depend on the engine); then the editor's branchFromStored() / branchToStored() and the run history's branchTakenText(). The test file's section 8 is the one that catches a forgotten walker.

Offering branches in a form's action list: the engine already runs them (runActionList() goes through executeActionList()). What is missing is the form editor's UI, and includes/services/forms.php validating the tree with validateActionTree().

Letting the AI co-author write branches: api/workflow/ai_compose.php describes the catalogue to the model; branches would need describing separately, and the AI's proposal validated with validateActionTree() before Apply.

7. Traps

  • TRAP: never foreach over the top level of an actions list when you mean "every action". Use webhookMapWebhooks() / WorkflowEngine::mapActionTree(). Listed on Code traps and in the engine guide.
  • TRAP: inside a branch, never call mergeStepResult() - see part 1.
  • A branch is not in availableActions(). Code that validates "is this a known action?" against the catalogue alone will reject every branched workflow - check BRANCH_TYPES as well, as the REST API now does.
  • The fallback is the last lane. The editor relies on it (splice(length - 1, 0, ...)); branchFromStored() always pushes it last, so it cannot drift.
  • Lookup values are text. The editor saves "4"; the engine compares as text; keep it that way.
  • step_log nests. A tool that reads step_log and expects a flat list of actions will miss every action inside a branch - walk steps, as the run history and the test's messages() do. (The Watchtower "needs a look" check searches the JSON text for "attention":, so it still finds a note left by a nested action.)

Related pages

Workflow branching - design Β· Workflows Β· Workflow engine - Developer Guide Β· Code traps

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally