Involve node

The Involve node starts a journey for another person, such as a partner or carer, and links the two journeys so they can signal each other.

The Involve node (code name Link) brings a second person into the patient's care. It finds that person (a relative, or a phone number or UHID given at enrolment), starts a journey for them, and links the two journeys. Once linked, either journey can wait for the other with a Pause, and send it signals with a Tell node.

When to use it

A fertility journey for the patient also starts a partner journey for semen analysis and counselling.
A paediatric journey starts a carer journey that sends the parent instructions.

Configuration

Field	What it does	Options and default
Label, Notes	See Label and Notes.	—
Journey to start for them	The journey the other person goes on. Required.	Your journeys.
Who to involve	How to find the other person. Required.	A relation of this patient (default), A phone or UHID from a start value, Staff pick the person (a task).
Relation	For a relation. Required. The relation recorded on the patient's Family tab.	Husband, Wife, Son, Daughter, Father, Mother, Same person.
Phone or UHID	For a start value. Required. An expression that gives a phone number or UHID.	For example `initial.partner_phone`.
This journey is the	The role name of this journey in the link. Required.	Free text, for example `patient`.
Their journey is the	The role name of the other journey. Required.	Free text, for example `partner`.
When nobody is found	Not shown for Staff pick the person (a task).	Take the "Nobody to involve" path (default) or Raise a task for staff to link them.
Role that gets the task	Shown when a task can be raised. Required then: Choose the role that gets the task.	Staff roles. Roles marked (no permissions yet) cannot be picked.

The panel notes: If the other person already runs that journey, the two are linked without starting a second one. Once linked, either journey can wait for the other with a Pause on "A linked journey…" events.

Involve has no Skip this step when… or If this step is already in the past fields.

Outcomes and branches

Pick one of these in the connection editor's Outcome list:

Outcome	When
The other person is on their journey	The person was found and is now on the other journey (newly started, or already on it), and the two journeys are linked.
Nobody to involve	The person could not be found and When nobody is found is set to take this path.
A task asks staff to link them	A task was raised for staff. See the limitation below.
Their journey refused the admission	The other journey refused to enrol the person, for example because of its cooldown.

What happens when it runs

The other person is looked up:
- A relation: the patient's active relation of the chosen type on the Family tab. If there are several, the one added first is used.
- A start value: a value that looks like a phone number is matched to a patient by phone number; anything else is matched as a UHID.
If the person is already on the other journey, the two journeys are linked without starting a new one.
Otherwise the person is enrolled on the other journey, which makes its usual enrolment checks. If they are refused, the outcome is Their journey refused the admission.
Once linked, each journey can wait in a Pause for the other journey's signals, start, end or cancellation (the A linked journey… events).

The other person receives whatever their journey sends them. Staff see both runs in the Patients tab of each journey; see Running journeys.

Example

Start the partner journey in a fertility programme.

Journey to start for them: Partner work-up.
Who to involve: A relation of this patient; Relation: Husband.
This journey is the patient; Their journey is the partner.
When nobody is found: Take the "Nobody to involve" path.
Connect Nobody to involve to an Engage step asking the counsellor to add the partner on the patient's Family tab.
Later, a Pause on the event journey.linked_signal with Signal name semen_analysis_done and From the role partner waits for the partner journey's Tell step.

Tips and limitations

Role names are free text. Use the same spelling on both sides and in every Pause and Tell that refers to them.
Record the relation on the patient's Family tab before the journey reaches this step; see The patient profile.
Simulate shows Involve steps as not available in this version — would fail here. Test Involve on a test patient instead. See Versions, drafts and simulate.

Task options do not work yet

An Involve step set to Staff pick the person (a task), or to Raise a task for staff to link them, fails when it needs to raise the task. Use A relation of this patient or A phone or UHID from a start value with Take the "Nobody to involve" path instead, and connect that path to a waiting Engage node that asks staff to add the person on the patient's Family tab. To try again once staff have done so, connect the Engage answer back to the Involve step, and give the Engage step a way out (for example Nobody answered in time to a Close).

journeysnodesinvolvelinked journeyspartnercarer