Auto-Assignment Rules

A dedicated Retool app lets care team managers create, modify, and delete rules that determine which care-team member is assigned to an intervention after it changes their state or subtype (custom field).

Scope

Auto-assignment is ECM-only and entirely optional.
If no rules are defined, interventions will not be auto-assigned.

---

1. How Auto-Assignment Works

Flow

1. Trigger – When an Intervention either

   • changes its state or subtype.

2. Callback fired – Active Record invokes a callback defined in the WithAutoAssignment

   before_validation :set_assignee

3. Rule Lookup

   • queries the auto_assignment_rules table for a rule that matches the Intervention’s new state/subtype;
   • reads the rule’s user_role.

4. User search – It searches the patient’s care pod for a user who holds that user_role. It follows the Assignment Logic described below.

5. Assignment – If a user is found, the Intervention’s assignee is set to that user.

Rules

• The rules are persisted in the auto_assignment_rules table described below:

Field	Description	Example
intervention_type	Class name	Ecm::Interventions::ProvideEducation
intervention_state	Intervention state	assess_knowledge
intervention_subtype	Optional subtype (see details below)	alcohol_use
user_role	Care-team role to assign	ecm_rn

• The Rails model for the rules is AutoAssignmentRules.

---

2. Managing Rules in Retool

1. Open the Auto-Assignment Rules app.

2. Click Add Rule to create a new rule, or click Edit next to each rule to update / delete.

3. Please complete the roles for all intervention steps.

Validation
There is a front-end validation that will prevent saving if any roles are left incomplete. This validation was implemented as a product decision to minimize user confusion, since subtype rules override generic rules. Refer to section 4.1 Creating Rules for more details.

---

3. Assignment Logic

1. For LCM or CES roles → the user is taken from the patient's ECM Profile.
2. All other roles → user selected from the patient’s Care Pod.
   • If multiple users share the role, it picks the one with the fewest open active interventions.
3. Fallbacks
   • If no user matches, assign Current.user.
   • If Current.user is the bot, fall back to the LCM.

Support for Out-of-Office (OOO) Coverage

If the LCM has designated a replacement during their OOO period, the intervention will be assigned to that replacement user.

For other care team roles, the intervention will be assigned to the replacement user if it is listed in REQUIRES_CARE_POD_COVERAGE

---

4. Intervention Subtypes

Support for subtypes was implemented later to cover additional use cases and allow more specific rules when needed. The valid subtypes for an intervention are defined in the intervention’s class and are tied to a custom field.

Example – ProvideEducation

• Custom field: education_type
• Allowed values: alcohol_use, substance_use, …

For a comprehensive list of subtype-aware interventions, see the doc.

4.1 Creating Rules

Given an intervention, you can create:

• Generic rules only: Rules that apply to all subtypes.
• Subtype-specific rules only: Rules that apply only to specific subtypes. For example, rules for alcohol_use , which is a subtype of ProvideEducation.
• Both generic and subtype-specific rules at the same time: You can set generic rules that apply to all subtypes, while also defining more specific rules for particular subtypes when needed.

Precedence
When both a generic rule and a subtype-specific rule match, the subtype-specific rule takes priority over the generic rule.

---

5. Logging

Every auto-assignment is logged, even if it assigns the same user again.

• Output: Rails logger (only enabled in production by default).
• Enable locally with ENABLE_AUTO_ASSIGNMENT_LOGS=true.

Logged data: intervention, previous assignee, new assignee, matching rule.

---

6. Technical Limitations

6.1 Excluded Interventions & States

Some interventions and states are intentionally excluded so existing behavior remains unchanged. For example, the first two states of Complete Form, whose assignee depends on form responses.

See this doc describing the interventions with behavior related to the intervention assignee.

6.2 Model Changes

When a new intervention state is added or an existing one is renamed, we need to ensure to update or create corresponding rules as there are no database constraints that warns us.

---

7. References

• Eng spec