Capability 04 · Plan engagement
Next-Best-Engagement
Turn an assigned HCP universe into one constrained action—or an explicit no-action outcome—per HCP for field review.
The problem¶
Engagement plans must balance tier coverage, recent activity, channel diversity, explicit consent, assigned ownership, minimum gaps, and visit capacity. A ranked list alone does not explain why an HCP is eligible or why no action is safer.
Objective¶
Recommend at most one action for each HCP, preserve the HCP's assigned representative, and expose plan metrics, capacity, channel mix, unassigned records, and no-action reasons for accountable review.
How it helps¶
- Loads a governed CSV universe and retains extra CRM columns that do not conflict with planner-owned fields.
- Scores eligible records with explicit weights and coverage constraints, then selects a consent-compatible channel.
- Fingerprints the loaded universe and fails closed if a later reload makes an earlier plan stale before export.
How the plugin works¶
Assigned HCP universe
A CSV with HCP, territory, and representative IDs; consent, tier, activity, and capacity fields refine eligibility.
Load, recommend, and export
load_universerecommend_engagementsrender_plan
Consent-aware engagement plan
Plan JSON or engagement and summary CSVs with actions, assigned owners, metrics, and no-action reasons.
A three-step workflow¶
Snapshot the universe
Load governed HCP, territory, representative, consent, tier, activity, and capacity fields.
Generate a plan
Apply minimum gaps, tier targets, weights, channel permissions, and visit-capacity rules.
Inspect actions and gaps
Challenge priorities, no-action reasons, ownership, channel mix, and field practicality before action.
Sample input¶
The public CSV is the exact built-in fictional demo fixture from the pinned 1.0.2 release: 80 HCP rows, 8 assigned representatives, and the full required-plus-optional universe columns used by the planner.
Interpreted sample output¶
The downloadable JSON shows that HCP-E-003 is a priority-1 in_person_visit, while HCP-E-015 is unassigned
with reason no_consent because neither email nor phone consent is explicitly true. The downloadable JSON was
generated from that same pinned fixture on 2026-08-30. Its metrics show 80 input HCPs, 76 eligible HCPs, 76 planned
actions, and 4 unassigned HCPs with no-action reasons. These counts describe one fictional demo universe only; they
are not a performance promise.
Download generated output JSON
Business value indicators¶
| Indicator | What a business reviewer learns |
|---|---|
| Total universe, eligible, and planned | How filtering and constraints change the actionable population |
| Coverage and tier gaps | Where the plan falls short of configured coverage targets |
| No-action count and reasons | Where consent, timing, or score rules prevent an action |
| Representative visit utilization | Whether proposed in-person work fits configured capacity |
| Channel mix | Whether the plan over-relies on one permitted mode |
Boundaries and human review¶
The planner does not send an email, book a meeting, perform a visit, or reassign account ownership. Confirm explicit consent, suppression lists, local policy, current interaction history, assigned representative and territory, capacity, and field practicality. Channel-diversity scoring does not replace these checks. Qualified business, privacy, and field reviewers remain accountable for every public-beta action.
Get started¶
Use the pinned 80-row fictional demo universe to inspect the consent and no-action logic, then consult the canonical pinned guide for the full CSV contract, plan fingerprint, and export behavior.