Entry rules and enrolling patients

Put patients on a journey automatically with entry rules, or enrol them by hand from Health, an entry rule or the patient profile.

A journey only does something once a patient is on it. Patients get onto a journey in one of three ways: an entry rule starts it when something happens in LeapHealthOS (a package is bought, an appointment is completed), a staff member enrols the patient by hand, or another journey starts it through a Connect or Involve step.

This page is for administrators who set up journeys and for front-desk and nursing staff who enrol patients. Before you start, the journey must be published. A journey with no published version cannot take patients (see Publishing and validation rules).

Every way in runs the same checks

Rules, manual enrolment and other journeys all pass the same admission checks: duplicate, cooldown, exclusion group, consent, hourly capacity and plan limits. Entry rules also check their own Who is eligible conditions. If a patient was not enrolled, see Why a patient was not enrolled.

Ways a patient enters a journey

How	Where it is set up	Who starts it
Entry rule	JourneysEntry rules	LeapHealthOS, when the chosen event happens
Enrol by hand	Enrol patients on the Health tab, Enrol existing patients… on a Start rule, or Enrol in a journey on the patient profile	A staff member
From another journey	A Connect node or Involve node in a running journey	The other journey

Whichever way the patient enters, the journey runs on its latest published version at that moment and stays on that version until it ends. Publishing a new version later does not move running patients. The patient profile shows this as "Started … on version N of this journey".

The Entry rules screen

Open JourneysEntry rules. The table lists every rule for your organisation, including rules that are switched off.

Column	What it shows
When	The event the rule listens for, with its group (for example Packages). A Not in catalog chip means the rule's event is no longer offered in the event list; the event's key is shown instead of its label.
Do	What the rule does: Start, Signal, Close or Pause.
Journey	The journey the rule acts on. "from step" means the rule starts patients part-way through.
Scope	Once per patient, or once per package purchase.
Attention	A Needs a look chip when the rule has a warning. Hover over it to read the warning.
On	The on/off switch. Rules that are off are never checked.
Actions	Edit, and for Start rules, Enrol existing patients…

Use the All and Packages chips to narrow the list. Packages shows only rules on package events, grouped by journey. When your rules target more than one journey, a Journey filter also appears.

Rules are switched off, not deleted

There is no delete button. To stop a rule, turn its On switch off. The rule stays in the list so you can see what used to happen and switch it back on.

Only staff whose staff type has the Configure permission on Journeys (set under SettingsPlatform ConfigurationSystem Settings, Organisation tab) can create, edit or switch rules and use Enrol existing patients…. Others see the rules read-only. See Who can do what in Journeys.

What a rule can do

Do this option	What happens when the event arrives
Start a journey	Enrols the patient named in the event. The admission checks still apply.
Signal a running journey	Sends a signal to the patient's newest running or paused copy of the journey, and to the journeys linked to it. A step waiting for A linked journey tells us something receives it and can move on.
Close the running journey	Ends the patient's newest running or paused copy of the journey. The outcome is shown as "Closed by an entry rule".
Pause the running journey	Pauses the patient's newest running copy of the journey.

A rule only acts on the patient the event names. An event that names no patient does nothing.

Create a rule

Open the rule editor

Administrator

Journeys > Entry rules

Select New rule.

Expected result: The New rule dialog opens.

Choose what happens

Pick the event in When this happens. Events are grouped as they are in the Event catalog. The description under the field explains the event.

Then choose Do this. For Start a journey, only events that can start a journey are listed. Lead signals (such as Lead form submitted) are not offered for any action. Changing the action clears the event you picked.

Pick the journey

Choose the journey in Journey.

Choose how often

In How often, choose Once per patient or Once per package purchase (see below).

Set the advanced options (optional)

Open Advanced to start part-way through, add conditions, limit who is eligible or hand details to the journey. Each option is described in the next section.

Save

Select Save.

Expected result: "Rule saved" appears. If the rule has a warning, the dialog stays open and shows it.

How often: once per patient or once per package purchase

Once per patient: a patient can only have one running or paused copy of this journey at a time. A second event for the same patient is refused as a duplicate. After the journey ends, the patient can enter again (subject to any cooldown).
Once per package purchase: one copy per package the patient buys. A patient who buys a second package gets a second copy of the journey. The event must name the package; if it does not, the rule does nothing.

For Signal, Close and Pause rules, Once per package purchase means the rule only acts on the copy of the journey that belongs to that package.

Advanced options

Option	What it does
Starts at	Start rules only. By default patients begin at the Start node ("Starts at: the journey's start node"). You can pick any step of the published journey instead. Earlier steps are recorded as "Step skipped at entry" and do not run. The list is empty until the journey is published ("Publish the journey first to choose a starting point").
Only when…	Conditions on the event's own details, for example only when the package is a particular one. Only the fields the chosen event provides can be used. Events that fail the condition are ignored.
Who is eligible	Conditions on Centre, Service, Payer and Doctor. A patient who does not match is refused with "does not meet the entry conditions of the journey". The values come from the event, so use only fields the event provides.
Hand over these details	Copies details from the event into the journey's starting values. The list on the left is the journey's initiation fields (set in Journey settings); required ones are marked `*` and must be mapped. If the journey has none, you see "The target journey declares no initiation fields — nothing to hand over."

What you can change after saving

After a rule is saved, the event, the action and the journey are fixed. The editor shows "Create a new rule to change what it does" and "Create a new rule to target another journey". You can still change How often, Starts at, Only when…, Who is eligible and Hand over these details.

To change the event, action or journey, create a new rule and switch the old one off.

Package journeys: pair a Start rule with a Close rule

A journey started by Package purchased or Package session redeemed should normally end when the package is cancelled or expires. Otherwise patients stay on the journey after the package is gone.

When you save a Start rule on Package purchased or Package session redeemed and the journey has no active Close rule for Package cancelled or Package expired, the rule gets a Needs a look chip and the dialog shows:

Journeys that start with a package usually end when it is cancelled or expires. Add a Close rule for those events so patients don't stay enrolled.

Select Add close rule in the warning. The dialog switches to a new Close rule for the same journey, with only the package-ending events offered. Pick the event and save.

The other warning appears when a rule repeats per package on an event that happens only once per patient (for example Patient activated):

This event happens once per patient, but the rule repeats per package — it will only ever run the first time. Switch to Once per patient, or pick a package event.

Warnings never block saving. They stay on the rule until you fix the cause.

Example: start an IVF programme when the package is bought

New rule: When this happens = Package purchased, Do this = Start a journey, Journey = your IVF journey, How often = Once per package purchase.
In Only when…, add a condition so only the IVF package starts the journey.
Save, then select Add close rule and create a Close rule for Package cancelled. Repeat for Package expired.

Enrol patients by hand

Use manual enrolment for patients who were already in the clinic before you created a rule, or for journeys you start case by case.

You can open the Enrol patients dialog from three places:

JourneysHealth, then Enrol patients (needs the Create permission on Journeys).
JourneysEntry rules, then Enrol existing patients… (the person icon) on a Start rule (needs the Configure permission on Journeys). The journey is filled in for you.
The patient's profile, Journeys tab, then Enrol in a journey. The patient is filled in for you. See The patient profile.

Choose the journey and patients

Administrator, front desk or nurse

Pick the Journey. In Patients, search by name or UHID and select one or more patients. The patient list comes from the clinic last selected in the clinic switcher. The switcher is not shown in Journeys, so to enrol patients from another centre, switch clinic on a screen such as All Patients first.

Check

Select Check.

Expected result: The dialog shows "X of Y can be enrolled". Patients who are already on the journey are listed under Cannot be enrolled.

Enrol

Select Enrol N patients.

Expected result: The dialog shows "N enrolled, M not enrolled", with one reason per patient under Not enrolled. Select Done.

Check only looks for duplicates

Check only finds patients who are already on the journey. Other reasons (cooldown, consent, exclusion group, hourly capacity, plan limit) appear only after you select Enrol N patients. Read the Not enrolled list each time.

Patients are enrolled one at a time. If the clinic's hourly limit of new patients is reached part-way through, enrolment stops. The remaining patients are listed as "not tried, because the hourly limit of new patients stopped the batch. Try again later".

Enrolling by hand never applies a rule's Who is eligible conditions; those only apply to entry rules.

What happens when an event arrives

How an entry rule is applied

1
Find the rules
Rules that are switched off are skipped.
Inthe event
Outevery rule that is switched on for that event
2
Check Only when…
Inthe event's details
Outrules whose conditions hold
On failure: the rule is skipped for this event
3
Find the patient
Inthe patient (and packagefor per-package rules) named in the event
Outthe patient to act on
On failure: nothing happens; there is no message on screen
4
Act
Start runs the admission checks, applies the handed-over details and begins at the Start node or the chosen step. Signal, Close and Pause act on the patient's newest copy of the journey that has not ended.
Inthe rule's action
Outa startedsignalledclosed or paused journey
On failure: for Start, the admission checks can refuse the patient

No record of rules that did not fire

LeapHealthOS does not show, anywhere on screen, when a rule was skipped or refused a patient. If you expected a patient to be enrolled automatically, work through Why a patient was not enrolled, then enrol the patient by hand to see the reason.

journeysentry rulesenrolmentenrol patientspackagestriggers