Quick Idea (Super Simple)

Think of this system like a GPS for your leads. A lead is always sitting in one Stage. When something happens (Event), the system checks the Rules and moves the lead to the next Stage.

• Stage = Where the lead is right now (a “status”).
• Event = Something that just happened (a “moment”).
• Rule = The instruction: “When this event happens, move to this stage.”
• Scenario = What type of lead this is (standard, price sensitive, etc.).

The engine’s question is always:
“Given this lead’s Stage + Scenario, and this Event just happened, what Rule should apply?”

How It Visually Flows

Important: Leads move between Stages. Events just happen. Rules decide the movement.

What You Should Do First (Daily Use)

1. Go to Workflow Admin → Coverage Dashboard (main page).
2. If you see anything in RED (missing wiring), click the Create rule / Add inbound rule links.
3. Keep the system “fully wired” so nothing goes to NULL or gets stuck.

Tip: The dashboard is like a “smoke alarm.” It tells you what’s broken before you feel it.

Understanding Each Section (Plain English)

Stages

• A Stage is a lead’s current status. Only one stage per lead at a time.
• Examples: new → tour_scheduled → enrolled
• Terminal = Yes means it’s the end of the story (ex: Enrolled, Lost).
• Sort Order is only for display order (it doesn’t change logic).
• Active = No means “don’t use it” (hidden from dropdowns).

Events

• An Event is a thing that happened (tour checked in, tour completed, no-show, etc.).
• Events trigger Rules. Events do not “hold” the lead — stages do.
• If an Event has 0 Rules, it’s “unwired” and the lead may not move correctly.

Rules

• Rules are the wiring between Events and Stages.
• They answer: “If this Event happens, where should the lead go next?”
• From Stage (optional) means “only apply this rule if the lead is currently in this stage.”
• Scenario (optional) means “only apply this rule for that scenario type.”
• Priority: if multiple rules match, higher number wins.
• To Stage blank means “no stage change.” (That can be okay, but too many of these can cause leads to look stuck.)

Scenarios

• Scenario is the “type of lead” or “playbook.”
• Example: Standard lead vs Price Sensitive lead can behave differently after the same event.
• Scenarios only matter if you have scenario-specific rules (rules where Scenario is selected).

Most Important Mental Model

A lead does not “move through events.” A lead moves through Stages. Events just happen along the way, and Rules decide how to react.

• Stage = where they are sitting right now
• Event = the thing that just happened to that lead
• Rule = what we do because that event happened
• Scenario = which playbook we apply

Step-by-Step Example: Add a New Scenario Playbook

Example new scenario: price_sensitive (These families need more reassurance on value, may take longer to decide, and may need extra follow-up.)

Step 1 — Create the Scenario

1. Go to Scenarios
2. Click Add / Edit Scenario
3. Code: price_sensitive
4. Label: Price Sensitive
5. Save

Step 2 — Decide what should be different vs Standard

Pick 1–2 points in the journey where this scenario behaves differently. Example: after tour_completed, standard leads might go to application_sent quickly, but price_sensitive leads might go to follow_up first.

Step 3 — Add scenario-specific rules (this is the “magic”)

1. Go to Rules
2. Create a new rule:
• Scenario: price_sensitive
• From Stage: tour_completed
• Event: tour_completed
• To Stage: follow_up
• Priority: 500 (example)
• Save
3. This rule will beat the global/default rule (because scenario-specific beats global).

Step 4 — Make sure the scenario is actually used

A scenario only changes behavior if leads have that scenario assigned. If a lead never gets assigned to price_sensitive, your scenario rules won’t run.

Today: scenario assignment might be manual or done by the system later (depending on your engine rules). Minimum viable approach: default most leads to standard, and manually set the scenario for special cases.

Step 5 — Validate with the Coverage Dashboard

• Scenario should NOT show under “Scenarios with 0 scenario-specific rules.”
• Events you rely on should not be “0 rules.”
• Stages you rely on should not be “0 inbound rules.”

Tour Lifecycle Example (How it “should” flow)

Here’s the typical sequence:

1. Lead Created → Stage becomes new
2. Contact Attempted → Stage becomes needs_contact
3. Contact Made → Stage becomes contacted
4. Tour Scheduled → Stage becomes tour_scheduled
5. Tour Checked In → Stage becomes tour_checked_in (if you want this stage)
6. Tour Completed → Stage becomes tour_completed
7. Then either:
   • Application Sent → application_sent
   • Application Received → application_received
   • Enrolled → enrolled (Terminal)
   • OR lead goes to follow_up if undecided
   • OR lost (Terminal)

Note: “We’ll think about it” is usually not an Event. It’s an outcome after the tour, and it typically means the lead should move into a follow-up Stage.

Common Mistakes (and how to fix them)

• Event is Unwired (0 rules)
  Fix: go to Rules → add at least one rule for that event.
• Stage has 0 inbound rules (dead stage)
  Fix: add a rule that goes TO that stage.
• Stage has 0 outbound stage-change rules (stuck stage)
  Fix: add a rule FROM that stage for a common event that moves it forward.
• Scenario exists but doesn’t change anything
  Fix: add at least one scenario-specific rule.

If something looks stuck, check the Coverage Dashboard on the main page.

Quick Recipes (Real-World Examples)

Recipe 1 — How to Create a “Tour Checked In” Stage Properly

Goal: When a family physically arrives for their tour, we want the system to reflect that they are now in a special stage: Tour Checked In.

Step 1 — Create the Stage

1. Go to Stages
2. Click Add / Edit Stage
3. Code: tour_checked_in
4. Label: Tour Checked In
5. Sort Order: Put it between Tour Scheduled (40) and Tour Completed (50). Example: 45
6. Terminal? No
7. Active? Yes
8. Save

Step 2 — Make Sure the Event Exists

• Go to Events
• Make sure you have an event called tour_checked_in

Step 3 — Add the Rule That Moves the Lead There

1. Go to Rules
2. Create a new rule:
• Event: tour_checked_in
• To Stage: tour_checked_in
• Priority: 100
• Active: Yes
3. Save

Step 4 — Make Sure They Can Move Forward

VERY IMPORTANT: The lead must also be able to leave this stage.

• Add a rule:
  • From Stage: tour_checked_in
  • Event: tour_completed
  • To Stage: tour_completed

If you forget this step, the stage will show as “stuck” in the Coverage Dashboard.

Recipe 2 — How to Handle “2x Tour No-Show” Properly

Goal: If a lead no-shows twice, we want to treat them differently (maybe mark them Lost or move to a special follow-up stage).

Understanding the Logic

The event tour_no_show happens each time they miss a tour. We need:

• A normal rule for first no-show
• A stronger rule for second no-show

Step 1 — Normal First No-Show Rule

1. Go to Rules
2. Create a rule:
• Event: tour_no_show
• To Stage: follow_up
• Priority: 100
3. Save

Step 2 — Add Special Rule for 2nd No-Show

This rule should only trigger if tour_count ≥ 2.

1. Create another rule
2. Event: tour_no_show
3. To Stage: lost (or high_risk_followup if you create one)
4. Priority: 500 (higher than 100 so it wins)
5. Conditions JSON:

[
  {"field":"tour_count","op":"gte","value":2}
]

Save the rule.

Why Priority Matters

If both rules match, the system picks the higher Priority. That’s why the 2nd no-show rule must have a higher number.

What Will Happen Now

• 1st no-show → Follow Up
• 2nd no-show → Lost (or escalation stage)

Check Coverage Dashboard after adding this to ensure:
• tour_no_show is wired
• follow_up has inbound rules
• lost is Terminal