Clinical Notification Service Admin Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.0.0 Last Updated: 2026-05-11 Module: CL (Clinical) Spec: CL-56 Status: Active

Purpose: Configure notification policies, escalation chains, and audit exports that govern how clinical signals reach staff.

---

​

Overview

The Centralized Clinical Notification Service routes signals (critical labs, medication exceptions, task assignments, etc.) into in-app alerts with severity, SLA, deduplication, and escalation behavior. As an administrator you control:

• Policies — per signal type: severity rules, SLA seconds, deduplication window, active toggle.
• Escalation chains — ordered recipient roles per severity tier.
• Audit log — searchable history of every dispatched event with CSV export.
• Feature flag — cl.notification_service_enabled global on/off switch.

---

​

Prerequisites

These keys are seeded to org_admin by default. Grant to additional roles via the Permissions page.

---

​

Enabling the Service

The service is governed by the global feature flag cl.notification_service_enabled (default: on).

1. Open Platform → Feature Flags.
2. Locate cl.notification_service_enabled.
3. Toggle off to immediately disable both the dispatch edge function (returns 503) and the three notification UI pages (“Feature unavailable” empty state).

No code change or redeploy is required to flip the flag.

---

​

Managing Policies

Path: Clinical → Notifications → Policies.

​

Create a Policy

1. Click New Policy (top right).
2. Fill the form:
   • Signal type — must match a publisher signal (e.g. lab_critical, medication_exception, task_assigned). Unique per organization.
   • SLA (seconds) — time before the alert escalates. Examples: 1500 (25 min) for critical labs, 28800 (8 h) for task assignments.
   • Dedup window (seconds) — identical signals on the same chart inside this window are suppressed. Use a longer window for noisy sources.
   • Severity rules (JSON) — optional rules that promote/demote severity based on payload fields. Default severity comes from the publisher.
3. Click Save.

​

Edit, Toggle, or Delete

• Edit — click a row, modify, save.
• Active toggle — switches dispatch on/off without losing configuration.
• Delete — the trash icon opens a confirmation dialog. Deletion is permanent; existing events remain in the audit log.

​

Severity Rule Tips

• Keep rules narrow and explicit; broad rules cause incorrect routing.
• Avoid PHI in rules — only payload metadata is allowed (a database CHECK constraint blocks PHI fields).

---

​

Managing Escalation Chains

Located on the same page, below Policies. Each chain is keyed by severity tier (critical, warning, info) and consists of ordered steps. Each step contains:

• Step order — 0 is the first recipient.
• Recipient role key — a system role (e.g. clinical_supervisor, medical_director, org_admin).
• Wait seconds — optional delay before the SLA evaluator can promote to this step.

​

Resolution Rules

1. The dispatch edge function reads step 0 for the alert’s severity, resolves the role to a user via pf_user_role_assignments, and creates the in-app notification.
2. When the SLA evaluator (cron, every 60 s) finds an unacknowledged event past its deadline, it advances to the next step and inserts a fresh event for the new recipient.
3. If no user is found for a role, the chain falls back to org_admin so alerts are never dropped.
4. When the chain is exhausted, the original event is marked sla_breached but no further escalation occurs.

​

Best Practices

• Always end the chain with org_admin (or your equivalent terminal role).
• Keep chains short (≤ 4 steps) — long chains delay clinically important escalations.
• Validate by triggering a synthetic event in a non-production org before publishing.

---

​

Audit Log and CSV Export

Path: Clinical → Notifications → Audit.

​

Filters

• Date range (required)
• Severity (multi-select)
• Signal type (multi-select)
• SLA status — On time / Breached

​

Columns

Dispatched At, Signal Type, Severity, Recipient, SLA Deadline, Acknowledged At, SLA Status, Escalation Step.

​

Export to CSV

1. Apply filters that scope the result set.
2. Click Export CSV.
3. The current filtered view is streamed as CSV (UTF-8, comma delimited).

Hard cap: 10,000 rows per export. Narrow the date range or filter further if you hit this limit. The CSV intentionally excludes free-text payload fields to minimize PHI exposure.

​

Retention

cl_notification_events rows are retained indefinitely. Coordinate with Compliance before bulk deletion; events are part of the clinical audit trail.

---

​

Operational Reference

​

Edge Functions

Both functions short-circuit when cl.notification_service_enabled is off.

​

Tables

• cl_notification_policies
• cl_notification_escalation_chains
• cl_notification_events — append-only event log with chk_cl_notification_no_phi CHECK constraint

RLS scopes every read/write to the active organization. The acknowledgement RPC cl_acknowledge_notification is SECURITY DEFINER and verifies access before stamping acknowledged_at / acknowledged_by.

---

​

Troubleshooting

​

Alerts are not being dispatched

1. Confirm cl.notification_service_enabled is on.
2. Verify a policy exists for the signal type and is active.
3. Check cl-clinical-notify logs for dedup hits or PF-10 insert errors.

​

Escalations are not advancing

1. Confirm a chain row exists for the next (severity, step_order).
2. Confirm a user holds the chain’s role in pf_user_role_assignments.
3. Inspect cl-notification-sla-evaluator logs for resolution failures (fallback to org_admin is logged as a warning).

​

CSV export is empty

• Check the date range; the default may not include recent events.
• Verify the requesting user has cl.notification_audit.export.

---

​

Related Documentation

• User Guide: cl-56-notification-service-user-guide.md
• Specification: specs/cl/specs/CL-56-centralized-clinical-notification-service.md
• Context: specs/cl/specs/CL-56-CONTEXT.md
• Implementation Log: specs/cl/IMPLEMENTATION_LOG.md
• Cross-core Integrations: docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md

---

Last Updated: 2026-05-11