Workflow Builder

The Workflow Builder

A workflow is automation drawn on a canvas rather than written. Nodes do things, edges connect them, and a run walks the graph.

Where to find it

Architect Panel → Automation:

• Workflow Builder — the canvas, nodes and edges
• Worklist — what is waiting on a person

Architect Panel → Automation:

• Tasks — the engine that resumes waiting runs

The parts

• The workflow — a name, a target datastore, a trigger, a status and the canvas.
• Nodes — each with a key, a type, its configuration and a position.
• Edges — from a node’s output port to another node, optionally labelled.
• Runs — one execution against one record.
• Steps — what each node did on that run.

The canvas is the definition

Not a picture of it. What you draw is what executes, which means the diagram cannot drift out of date — a problem every documented-elsewhere automation eventually has.

Every node has ports

Most have one output; a condition has two, true and false. Edges leave a specific port, which is what makes branching explicit rather than implied by ordering.

A run belongs to one record

Started by something happening to that record, walking the graph, recording each step. So "what did the system do to this record" has a precise answer.

Runs are claimed

Each in-progress run holds a claim token, so two engine passes cannot process the same run simultaneously. That is what makes waits and resumption safe rather than a source of duplicated actions.

Runs have a step budget

The number of steps taken is tracked, which bounds a workflow that loops. A cycle in the graph is a mistake that is easy to draw and would otherwise run forever.

When a workflow is right

• Several steps in sequence with branching.
• Anything involving a wait, an approval or a timer.
• Anything somebody other than a developer should be able to read.

When something else is right

A single field update on save is a rule, not a workflow. A recurring job across many records is a task. Workflows are for a process that happens to one record over time.

Build it in draft

A workflow has a status, and only active ones run. Draw it, review it, then activate — because an active workflow acts on real records from the moment it is switched on.

Worked example

An organisation runs a complaint-handling workflow: acknowledge, wait, check whether it has been assigned, escalate if not, request approval before closure. Drawn on one canvas, readable by the complaints manager, with every run showing exactly which path a case took.

Recommendations

• Workflows for processes, rules for single updates, tasks for batches.
• Build in draft and activate deliberately.
• Avoid cycles — the step budget will stop them, untidily.
• Draw it so a colleague can read it.

Triggers

A workflow names the datastore it acts on and what starts it.

Where to find it

Architect Panel → Automation:

• Workflow Builder — the canvas, nodes and edges
• Worklist — what is waiting on a person

The trigger has three parts

• Type — an event on a record, or a schedule.
• Event — what happened.
• When — before or after that event is processed.

Only active workflows are matched, so a draft can exist safely alongside a live one.

Before or after

The decision that causes most confusion.

• Before — the workflow runs while the change is still in progress. Use it where you need to affect the record as it is saved.
• After — the change is committed. Use it for anything reacting to a settled fact: notifying, creating related records, starting a process.

After is right most of the time. Before is for the cases where the change itself needs to be shaped.

Scheduled workflows

Run on a frequency rather than in response to a record change. Useful for anything that has to happen regardless of activity — a periodic review, a sweep for records that have gone stale.

One trigger per workflow

Which keeps each one comprehensible. A workflow that should start in two circumstances is usually two workflows, or one workflow whose first node is a condition.

Beware the loop

A workflow triggered by an update that itself updates the record will trigger again. The step budget stops it eventually, and eventually is not soon enough.

Where a workflow writes to its own target, make the trigger narrow enough that the write cannot match it.

Narrow the trigger, not just the condition

A workflow that starts on every save and immediately evaluates a condition starts constantly. Where the trigger can be more specific, make it so — it is cheaper and the run history stays readable.

Think about volume

A trigger on a high-volume datastore starts a run per record. Consider what that means during an import of ten thousand rows, and whether the workflow should be excluded from bulk operations.

Test the trigger first

Before building the rest. Activate a workflow with a single harmless node, cause the event, and confirm a run appears. Establishing that the trigger fires removes the largest unknown.

Worked example

A workflow triggers after a case is created, not before, because everything it does depends on the record existing. A second workflow triggers after a status change specifically, rather than on any update, so an import of notes does not start thousands of runs.

Recommendations

• After, unless you need to shape the change.
• Narrow the trigger rather than filtering afterwards.
• Watch for self-triggering loops.
• Prove the trigger fires before building the workflow.

Node Types

Fifteen node types cover what a workflow can do.

Where to find it

Architect Panel → Automation:

• Workflow Builder — the canvas, nodes and edges
• Worklist — what is waiting on a person

Structure

• Trigger — where a run starts.
• Condition — two output ports, true and false.

Changing data

• Update — set fields on the record.
• Status — set the status field specifically, which also writes to the activity stream so the change is visible in the record’s history.
• Create — make a related record.
• Convert — create a record in another datastore from this one, mapping fields across and linking the two.

Status rather than update, where you are setting a status: the activity entry is the difference between a history somebody can read and a field that silently changed.

Communicating

• Email, SMS, WhatsApp and Letter.

Four channels from the same canvas. Choose by what the recipient will actually receive rather than by what is convenient — a letter for something formal, a message for something urgent.

Time

• Wait — pause until a point in time, then resume.
• SLA — a timer with a target, resuming on one path if met and another if breached.

Both suspend the run, which is resumed later by the task engine. That is what allows a workflow to span days without holding anything open.

People

• Approval — pause until somebody decides.
• Signature — pause until a document is signed.
• Verification — pause until an identity check completes.

These are what make a workflow a process rather than a script: it waits for a person, indefinitely, without anybody holding state.

Overlaps worth knowing

• Update against status — use status for statuses.
• Create against convert — convert where the new record derives from this one and should be linked.
• Wait against SLA — wait for a delay, SLA where meeting the deadline matters and the two outcomes differ.

Label the edges

Particularly out of conditions and SLA nodes. "True" and "false" tell you nothing six months later; "approved" and "referred" tell you what the branch means.

Worked example

A complaints workflow uses trigger, status, email, SLA, condition, approval and letter — acknowledging by e-mail, running a five-day SLA timer, escalating on breach, requesting approval before closure and sending the outcome by letter. Every edge is labelled.

Recommendations

• Status nodes for statuses — they write to the activity stream.
• Convert where the record derives from this one.
• SLA where the deadline matters, wait where it does not.
• Label every edge meaningfully.

Conditions and Branching

A condition node evaluates a test and sends the run down one of two paths.

Where to find it

Architect Panel → Automation:

• Workflow Builder — the canvas, nodes and edges
• Worklist — what is waiting on a person

Two ports, always

True and false. Both should go somewhere — a false branch with no edge is a run that stops silently, which looks identical to a run that finished.

If nothing should happen on one branch, connect it to something that says so rather than leaving it dangling.

One question per condition

A condition testing three things at once is a condition nobody can debug, because a run down the false branch could have failed any of the three.

Chained conditions are longer to draw and enormously easier to read in the run history, where each step is recorded separately.

Put the common path first

Most runs should follow a short, obvious route. Exceptions branch off it. A canvas where the ordinary case wanders through six conditions is one nobody can reason about.

Label the edges

What the branch means, not which port it left. "Over £5,000" and "Standard" are readable; "true" and "false" require reading the condition every time.

Beware the empty branch

The commonest bug in a workflow. A condition where somebody drew the true path and forgot the false one, so a proportion of records silently stop part way through a process.

Nothing errors. The run simply ends, and it looks like every other completed run.

Test both branches

Every condition, both ways, with real records. Testing only the path you expected is how a false branch reaches production untested — and it is the branch that handles the awkward cases.

Watch for conditions on values that change

A condition evaluated after a wait sees the record as it is now, not as it was when the run started. That is usually what you want and occasionally a surprise — a case closed during a three-day wait will take an unexpected branch.

Keep the canvas readable

Node positions are stored, so layout is yours to control. Left to right, branches down, no crossing edges where avoidable. A workflow is documentation as well as automation, and a tangle is neither.

Worked example

An approval workflow branches on value, then on whether the requester is in a particular team, as two separate conditions rather than one combined test. Both branches of each go somewhere. The run history shows which specific test sent a case down the escalation path.

Recommendations

• Connect both ports of every condition.
• One question per condition.
• Label edges by meaning.
• Test both branches with real records.

Waits and Timers

A workflow can pause. That is what makes it a process rather than a script.

Where to find it

Architect Panel → Automation:

• Workflow Builder — the canvas, nodes and edges
• Worklist — what is waiting on a person

Architect Panel → Automation:

• Tasks — the task that resumes waiting runs

Architect Panel → Data:

• Business Hours Calendars — working hours for timers

How pausing works

A run that reaches a wait or a timer records when it should resume and which port it will leave by, then stops. A scheduled task periodically picks up runs whose time has passed and continues them.

So nothing is held open, and a workflow can span days or weeks at no cost.

Wait against SLA

• Wait — pause, then continue. One outcome.
• SLA — a target with two outcomes, met or breached, each continuing down its own path.

Use a wait for "send a reminder three days later". Use an SLA for "respond within four hours or escalate", because the two outcomes genuinely differ.

The resume task must be running

The practical consequence. If the task that resumes waiting runs is disabled or failing, every workflow with a wait quietly stops mid-process.

Nothing errors — runs simply sit. When workflows "stop working", check that task first.

Working hours, not wall-clock

A four-hour target should mean four working hours. An SLA measured against the clock reports every Friday afternoon request as breached by Monday, and the team is not at fault.

Waits must be bounded

A run waiting for something that never arrives waits forever. Where a wait depends on an external event, pair it with a timer so the process has a way out.

The record may change while waiting

Three days is long enough for a case to be closed, reassigned or deleted. A workflow resuming into a changed situation should check before acting — sending a chaser about a resolved case is a small failure that customers notice.

A condition immediately after a long wait is usually worth having.

Watch how many runs are waiting

A growing population of waiting runs means either a resume task that is not running or a wait nothing satisfies. It is a useful number to look at occasionally.

Test with short waits

Build with a wait of a few minutes, confirm the whole path works, then set the real duration. Testing a three-day wait by waiting three days is how workflows go live untested.

Worked example

A workflow acknowledges a request, runs a four working-hour SLA timer, escalates on breach and continues on success. A three-day chaser wait is followed immediately by a condition checking the case is still open. Both were tested with two-minute durations first.

Recommendations

• Check the resume task when workflows stall.
• SLA timers against working hours.
• Re-check the record after a long wait.
• Test with short durations, then set the real ones.

Building and Testing

Workflows act on real records the moment they are active. The sequence below is how to avoid finding that out the hard way.

Where to find it

Architect Panel → Automation:

• Workflow Builder — the canvas, nodes and edges
• Worklist — what is waiting on a person

Build in this order

1. Write down the process in sentences first. If you cannot, the workflow will not help.
2. Create it as a draft with its trigger.
3. Prove the trigger fires with a single harmless node.
4. Add the happy path, end to end.
5. Add branches, connecting both ports of every condition.
6. Add waits and timers, with short durations.
7. Test every path with real records.
8. Set the real durations and activate.

Prove the trigger before anything else

It removes the largest unknown. A workflow that is not running at all and one that is running and failing look identical until you know a run was created.

Test on records that do not matter

The workflow sends messages, changes statuses and creates records. Use test records, and make sure any e-mail address involved is one you control.

A workflow tested against real customer records has contacted real customers.

Test every path

Not the one you expected. Each branch, each SLA outcome, each approval decision. The untested branch is always the one that handles the difficult case, which is where it matters most.

Read the run history for each test

It records every step and its outcome. That is where you see a node that succeeded but did nothing, or a branch that went the way you did not intend.

Activating is a live change

From that moment it acts on real records, including ones already in flight. Consider what a workflow triggering on status change does to a hundred records somebody bulk-updates that afternoon.

Watch the first day

Look at the runs that happened, not at whether anybody complained. Most workflow problems are visible in the first day’s history and invisible to users until later.

Change it the same way

A change to a live workflow is a live change. There is no draft copy of an active workflow, so significant changes are best made by building a replacement and switching over.

Tell people

A workflow changes what the system does to their work. Somebody who receives an unexpected automated message about their own case will raise it as a fault.

Worked example

A team wrote its process down, proved the trigger, built the happy path, then tested each of five branches with test records and read the run history for each. It activated on a Tuesday morning and reviewed every run that afternoon, which caught a condition branching the wrong way for one case type.

Recommendations

• Prove the trigger first.
• Test with records and addresses you control.
• Test every branch, reading the run history each time.
• Review the first day’s runs after activating.

The Run History

Every execution is recorded as a run, and every node it reached as a step.

Where to find it

Architect Panel → Automation:

• Workflow Builder — the canvas, nodes and edges
• Worklist — what is waiting on a person

What a run records

The workflow, the record, its status, which node it is at, how many steps it has taken, what it is waiting for and until when, its context, and when it started and finished.

What a step records

Which node, its status, a detail, and when. So the run history is a readable account: this happened, then this, then it branched here, then it waited.

It answers the question people ask

"Why did this customer get that e-mail" or "why was this not escalated" is answered by opening the run for that record and reading. That is much better than reasoning about the canvas.

Status tells you where a run is

• Running — in progress.
• Waiting — suspended at a wait, timer or approval, with its resume time recorded.
• Finished — completed.

A population of runs stuck at waiting is the signature of a resume task that is not running.

Steps taken is a health signal

A run with an unusually high step count has probably looped. The count is bounded, so it will stop — but the count itself is what tells you the graph has a cycle.

Look for runs that ended early

A run finishing after two steps in a nine-node workflow ended somewhere it should not have — almost always an unconnected condition port. Comparing step counts across runs finds those quickly.

Read it before changing the canvas

When a workflow is misbehaving, the run history says what actually happened. Changing the canvas based on what you think it does, without reading a real run, is how a second bug is added to the first.

Use it as evidence

For a complaint, an audit or a dispute, the run history is a record of what the system did and when. That is worth more than a description of what it was supposed to do.

It grows

A run and several steps per record. On a high-volume datastore that accumulates quickly, so include it in whatever retention thinking covers your other logs.

Worked example

A customer asked why they had not been contacted. The run for their case showed it had reached the condition after the acknowledgement and taken the false branch, which had no edge. The workflow was corrected and the affected cases identified from their step counts.

Recommendations

• Read a real run before changing the canvas.
• Compare step counts to find runs that ended early.
• Waiting runs piling up means the resume task.
• Include run history in your retention planning.