Enhancements 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-02-26
Module: CL (Clinical & EHR)
Status: Active

Purpose: This guide helps administrators configure, manage, and troubleshoot EN-27 (Server-Side CDS Evaluation), EN-28 (Clinical Pathways), and EN-29 (CDS Alert Analytics).

---

​

Overview

These three enhancements extend the CL-08 Clinical Decision Support module:

​

Admin Responsibilities

---

​

Prerequisites

​

Required Permissions

​

System Requirements

• CDS rules must be configured (cl_cds_rules table) before EN-27/EN-29 produce data
• The evaluate-cds Edge Function is auto-deployed — no manual deployment needed

---

​

Initial Setup

​

Step 1: Assign Permissions

Assign permissions based on clinical roles: To assign permissions:

1. Go to Settings → Roles & Permissions
2. Select the role to modify
3. Under the Clinical module, enable the required permissions
4. Save changes

​

Step 2: Configure CDS Rules

CDS rules drive both EN-27 (evaluation) and EN-29 (analytics). Without active rules, the system generates no alerts.

1. Navigate to Clinical → CDS Rules
2. Create rules with appropriate types:
   • drug_interaction — Checks for interactions between drug classes
   • drug_allergy — Cross-references medications with allergies
   • quality_measure — Flags missing assessments
3. Set each rule’s trigger_event, severity, and condition.parameters
4. Mark rules as Active

​

Step 3: Review Pathway Definitions

If clinical pathways have been created:

1. Navigate to Clinical → Clinical Pathways → Pathway Management
2. Review each pathway for clinical accuracy
3. Deactivate any pathways that are not yet approved for use

---

​

Configuration Reference

​

EN-27: Edge Function Configuration

The evaluate-cds Edge Function requires no secrets or environment variables — it uses the public RxNav API (no authentication needed).

​

EN-28: Database Tables

RLS Policies:

• SELECT/INSERT/UPDATE: cl_has_org_access(organization_id, auth.uid())
• DELETE: cl_is_org_admin(organization_id, auth.uid()) — admin only
• UPDATE includes WITH CHECK to prevent cross-tenant data movement

​

EN-29: Analytics Data Source

Analytics aggregate from cl_cds_alerts with joins to cl_cds_rules (rule names) and pf_profiles (provider names).

---

​

Routine Administration

​

Weekly Tasks

• Review CDS Alert Fatigue Dashboard for override rates > 50%
• Check evaluate-cds Edge Function logs for errors or sustained degraded mode

​

Monthly Tasks

• Audit pathway definitions for clinical accuracy and relevance
• Review per-provider alert metrics for training opportunities
• Tune or deactivate CDS rules with consistently high override rates

​

Quarterly Tasks

• Comprehensive review of all active CDS rules against current clinical guidelines
• Evaluate pathway step content for evidence-based updates
• Generate alert fatigue report using 90-day time window

---

​

Monitoring and Reports

​

Edge Function Health (EN-27)

Monitor the evaluate-cds function:

​

Alert Fatigue Metrics (EN-29)

​

Pathway Usage (EN-28)

---

​

Troubleshooting

​

Issue: Users Can’t Access Pathways

Symptoms: Users see “Access Denied” shield on /cl/pathways Diagnostic Steps:

1. Check user’s role assignments in Settings → Roles & Permissions
2. Verify role includes cl.pathways.manage permission

Resolution: Assign cl.pathways.manage to the user’s role.

---

​

Issue: No Alerts Generated by EN-27

Symptoms: evaluate-cds returns { alerts: [], pass: true } even with known interactions. Diagnostic Steps:

1. Verify CDS rules exist and are active (cl_cds_rules.is_active = true)
2. Check that medications have status = 'active'
3. Check if medications include rxcui values (required for RxNav checks)
4. Review Edge Function logs for errors

Resolution:

• Ensure active CDS rules with correct condition.parameters (drug_class_a, drug_class_b)
• For RxNav interaction checks, medications must have valid rxcui codes
• For allergy checks, verify patient allergy records exist

---

​

Issue: CDS Analytics Shows Stale Data

Symptoms: Dashboard data doesn’t reflect recent alerts. Cause: Query cache (5-minute staleTime). Resolution: Refresh the page. Data updates automatically after 5 minutes.

---

​

Issue: Edge Function in Sustained Degraded Mode

Symptoms: Logs show repeated RxNav API unavailable warnings. Diagnostic Steps:

1. Check RxNav API status
2. Review Edge Function logs for timeout or network errors
3. Verify Edge Function can reach external URLs

Resolution:

• If RxNav is down, no action needed — the system operates safely in degraded mode
• Text-based rule matching continues to function as a fallback
• Monitor for when RxNav returns to normal operation

---

​

Escalation Path

1. Check Edge Function logs at Supabase Dashboard
2. Review cl_cds_alerts table for recent entries
3. Contact technical support with:
   • request_id from the CDS evaluation response
   • Time range of the issue
   • Screenshot of the analytics dashboard

---

​

Security Considerations

​

Data Access

• All CDS data is tenant-isolated via RLS policies with organization_id filtering
• Provider metrics in analytics resolve names from pf_profiles — no PHI exposed
• The evaluate-cds Edge Function validates JWT auth and org access before processing

​

Audit Trail

• Every CDS evaluation includes request_id, request_timestamp, and latency_ms
• Alert persistence creates records in cl_cds_alerts with full provenance
• Break-glass access to CDS data follows standard clinical audit patterns

​

External API Security

• RxNav API is public (no API key) — no secrets to manage
• 5-second timeout prevents Edge Function hangs
• No PHI is sent to RxNav — only RxCUI codes (standardized drug identifiers)

---

​

Best Practices

​

Configuration Best Practices

• ✅ Start with a small set of high-value CDS rules and expand based on analytics
• ✅ Set appropriate severity levels — reserve critical for true hard-stop scenarios
• ✅ Review override rates monthly and deactivate rules with > 70% override rates
• ✅ Define pathways with clear, measurable completion criteria at each step

​

Security Best Practices

• ✅ Restrict cl.cds_rules.manage to supervisors and quality staff
• ✅ Review provider-level alert metrics to identify potential compliance gaps
• ✅ Ensure all pathway definitions are reviewed by a licensed clinician before activation

​

Performance Best Practices

• ✅ Keep active CDS rule count reasonable (< 50 rules per organization)
• ✅ Use RxCUI codes on medications for more accurate interaction checks
• ✅ Archive completed pathway progress records periodically

---

​

Data Management

​

Data Retention

​

Soft Delete

Pathway definitions use soft delete (deleted_at timestamp):

• Deleted pathways are hidden from the UI but preserved in the database
• Only org admins can delete pathways (RLS policy)
• Existing progress records linked to deleted pathways remain accessible

---

​

Integration Points

---

​

Change Log

---

​

Related Documentation

• User Guide: docs/guides/cl/cl-08-cds-enhancements-user-guide.md
• Specification: specs/cl/specs/CL-08-ENHANCEMENTS.md
• Edge Function Logs: Supabase Dashboard

---

Last Updated: 2026-02-26
Technical Support: Contact your organization’s system administrator.