The builder canvas and how connections work

The journey builder is a canvas where you lay out the steps of a journey and draw the connections between them. This page explains how to add, edit and delete steps, and, most importantly, how the connections decide where a patient goes next. It is written for the administrators and implementation staff who design journeys.

The parts of the canvas

When you open a journey from JourneysJourneys, the builder shows:

• The palette on the left, with every kind of step you can add. It is hidden while the canvas is read-only.
• The canvas in the middle, with your steps (nodes) and the connections (edges) between them.
• The header along the top, with Save, Publish and the other journey-level controls. These are described in Creating and managing journeys.

You can pan by dragging the empty canvas, zoom with the zoom controls or your mouse wheel, and use the minimap in the corner to jump around a large journey. The canvas fits the whole journey into view when it opens.

Adding steps

The palette groups the 15 step types:

Click a tile to add that step. The new step is placed to the right of the step you have selected (or the last one you added) and is selected for you. On an empty canvas it appears near the top-left of the current view.

A journey can have only one Start step. If you try to add a second one you see A journey can only have one Start node.

For what each step does and how to configure it, see the Node reference overview.

Reading a step card

Each step on the canvas is a card. It shows:

• The step's label, or its type if you have not named it, with a subtitle such as Engage · Task that names the step type.
• A short summary of how the step is configured.
• Not configured when you have never opened and saved the step.
• Needs setup when a required field has no value yet.
• n incoming branches — consider Gather when more than one connection arrives at a step that is not a Gather. See "Bringing parallel tracks back together" below to decide whether you need one.
• Convergence point · n incoming branches on a Gather step.

The connection points (handles) are on the sides of the card: the input on the left, the output on the right. Steps that can host an AI Aide (Reach, Capture, Engage, Appointment, Connect, Produce) also have an attachment handle at the bottom. Start has no input, and Close has no output.

Editing a step

If you close the dialog with unsaved changes, you are asked Journey Node is Not Saved — "You have unsaved changes, do you want to exit?". Choose Yes to discard the changes or Cancel to keep editing.

Step names must be unique

Two steps cannot share a label. Names are compared without regard to capital letters, and spaces count as underscores, so "Intake call" and "intake_call" are the same name. If you try to reuse a name you see Another node already uses this name — node names must be unique. The rule exists because other steps and conditions read a step's results by its name (for example context.nodes.intake_call). Two steps with one name would make those references ambiguous.

Deleting steps and connections

• Open the step's menu and choose Delete Node, or select the step and press Backspace.
• Deleting a step also deletes every connection into or out of it.
• To delete a connection, hover over it and select the bin icon, or drag one end of it off its step and drop it on empty canvas.

Connecting steps

Drag from a step's output handle (right) to another step's input handle (left). The connection appears as a dashed arrow. To move an existing connection, drag its end onto a different step.

The canvas refuses a connection that breaks these rules:

• A step cannot connect to itself.
• Nothing can flow into Start, and nothing can flow out of Close.
• An AI Aide never takes part in the flow. It only uses the dashed attachment connector.
• You cannot draw a second plain connection between the same two steps. (A plain connection has no condition and is not a default.)

Publishing checks the same rules again. See Publishing and validation rules.

Attaching an AI Aide

An AI Aide fills in some of the inputs of the step it is attached to. It is not a step the patient passes through. Drag from the AI Aide's top handle to the bottom handle of a Reach, Capture, Engage, Appointment, Connect or Produce step. The attachment shows as a dashed orange line. Hover over it to delete it.

Each AI Aide attaches to one step, and each step can have at most one AI Aide. See AI Aide node.

How connections fire

This is the most important idea in the builder. When a step finishes, the journey looks at every connection leaving that step and decides which ones to follow. A connection is one of three kinds:

The rules that follow from this:

1. Every connection that qualifies fires. The journey does not pick one. Two plain connections out of a step start two tracks that run at the same time (in parallel).
2. Conditioned connections are not exclusive. If two conditions are both true, both connections fire. Make conditions that cannot overlap when you want a patient to go one way only.
3. A default connection only looks at conditioned connections. Plain connections do not count. A default next to a plain connection therefore fires whenever no condition matched, in parallel with the plain one.
4. If nothing fires, the track ends silently. The patient's track stops at that step with no outcome. If it was the only track still running, the patient's journey ends there. Give every set of conditioned connections a default to avoid this.
5. A Close step ends the track, or the whole journey. Its Scope decides: Branch — siblings continue ends only this track; Instance — end everything also cancels every other live track.

In this example Start has two plain connections, so the welcome message and the intake call happen at the same time. The intake call routes: if staff record reached, the patient goes to the Gather; for any other answer (including Nobody answered in time), the default sends them to a retry call. The Gather waits for both tracks before moving on, and has its own outcomes for when they all arrive (met) or its timeout runs out (timeout).

Bringing parallel tracks back together

If two parallel tracks lead into the same ordinary step, that step runs once for each track that reaches it, and so does everything after it. A patient could get the same message twice, or two copies of a task.

Use a Gather step wherever parallel tracks rejoin. A Gather waits for the incoming tracks according to its Policy (All, Any or K of N), then continues once. Tracks that have already ended are left out, so a Gather set to All does not wait for a track that can no longer arrive. See Gather node.

You do not need a Gather when the incoming connections are alternatives, for example two conditioned connections from the same step that can never both be true. The card still shows n incoming branches — consider Gather, but publishing only warns about it when the tracks really run in parallel.

The connection editor

Hover over a connection and select the branch icon (Edit edge), or click its label chip. The editor has these fields, from top to bottom:

Select Apply to keep your changes or Cancel to discard them. The outcome, branch and condition rows are combined with AND: the connection fires only when all of them hold.

The chip on the connection summarises it: default, or the branch, outcome and first condition (for example reached · initial.risk_tier == "high" AND +1 more). A plain connection has no chip.

Fields you can use in conditions

The Field list offers what the journey knows at that point. You can also type a field path yourself.

Values are typed for you: true, false and null become those values, whole and decimal numbers become numbers, and anything else is compared as text, exactly as typed. Operators are ==, !=, >, >=, <, <=, exists and not exists.

Outcomes you can pick, by step

A Gather reports impossible when it can no longer be satisfied (for example, a K of N Gather where too few tracks are still alive). If no connection handles impossible, the Gather reports timeout instead, so a timeout connection covers both cases.

When an action step is skipped by its Skip this step when… condition, it finishes with the outcome skipped. Route it with a condition on Completed outcome if the skipped case needs its own path.

Common mistakes

Related pages

• Journeys overview and concepts
• Waiting, time limits and reminders
• Publishing and validation rules
• Node reference overview