Skip to main content

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.

Feature ID: CL-17
Status: 🏗️ Scaffolded (gateway integration pending vendor selection)
Spec: CL-17-arizona-cspmp-pdmp-integration.md
Last Updated: 2026-02-23
Last Verified: 2026-02-23

​
Cross-Core Integration Matrix

From CoreTo CoreIntegration PatternStatusDocumentation
CL (CL-17)CL-06, CL-01, External gatewaysAPI / query-in-workflow🏗️ ScaffoldedCL-17 spec

​
Overview

CL-17 defines Arizona Controlled Substances Prescription Monitoring Program (CSPMP) / PDMP integration: query-in-workflow for controlled substance prescribing, prescriber attestation, delegate access, and audit trail per A.R.S. § 36-2606. Integration with external gateways (PMP Gateway/NABP, Bamboo Health/Appriss, Arizona HIE) and with CL-06 (e-prescribing) and CL-01 (patient chart). Query-in-workflow (fail-closed): Query-in-workflow MUST be fail-closed. Clinicians must NOT prescribe controlled substances when a required PDMP query fails or is unavailable unless an exception is recorded. Enforce at the application layer and in workflows that use cl_pdmp_queries; see Security and RLS below.

​
Integration Points

DependencyPatternPurpose
CL-06 (E-Prescribing)DirectPDMP query embedded in e-prescribing workflow for controlled substances
CL-01 (Patient Chart)DirectPDMP query history on patient chart
CL-08 (Clinical Decision Support)Planned (future)PDMP results (high-risk indicators) may trigger CDS alerts in e-prescribing flow
PMP Gateway (NABP)ExternalPDMP query API
Bamboo Health / ApprissExternalPDMP query API
Arizona HIEExternalPDMP query API

​
API / Data Contracts

​
External gateway (PMP Gateway / Bamboo Health / Arizona HIE)

  • Authentication: Credentials MUST be loaded from the platform vault only via credentials_vault_ref; no API keys or tokens in code or config. Use the existing platform vault pattern.
  • Request/response: Request/response schemas for PDMP gateway calls to be defined when implementation is chosen (e.g. patient identifiers, date range, prescriber/delegate context). Document in this section when available.
  • Resilience (API alignment): Use a per-attempt timeout of 5s (aligned to NFR-1). Retry policy: 2 retries with exponential backoff (initial delay 200ms, multiplier 2, max backoff 1s). Maximum total timeout: 15s; after that the integration MUST fail-closed (do not allow prescribing without recording the failure). Any fail-closed event or gateway unavailability MUST be recorded in cl_pdmp_queries with results_summary.exception_type set to pdmp_unavailable. Include diagnostic fields in results_summary for debugging (e.g. attempt_count, last_error).
  • Rate limiting: If the gateway documents rate limits, implement client-side throttling per org/facility and document limits in this section when known.

​
cl_pdmp_queries

  • Scope: organization_id + chart_id; PHI — full RLS.
  • Key columns: chart_id, queried_by, queried_on_behalf_of, prescriber_attestation, results_reviewed_at, prescription_id, gateway_transaction_id, gateway_provider, interstate_query, states_queried.

​
cl_pdmp_configuration

  • Scope: organization_id; org-level gateway and feature toggles.
  • Key columns: gateway_provider (CHECK: pmp_gateway | bamboo_health | arizona_hie), auto_query_enabled, interstate_query_enabled, delegate_access_enabled, credentials_vault_ref.

​
Event Contracts

​
cl_pdmp_query_completed (Planned — Deferred)

Status: Planned but deferred from initial implementation.
Rationale: CL-17 uses synchronous query-in-workflow. The cl_pdmp_queries table INSERT is the primary audit trail per A.R.S. § 36-2606. A domain event is not required for the core compliance use case. The event will be implemented if downstream consumers need to react to PDMP queries (e.g., CL-08 CDS high-risk alerts, GR compliance automation). When to implement: When CL-08 or GR needs to subscribe to PDMP query completion for automated processing. Registered in: src/platform/events/types.ts as KnownEventName (cl_pdmp_query_completed); EVENT_CONTRACTS.md planned events table. Subscriber controls (required before release):
  • Channel subscribers must be explicitly allowlisted and limited to approved consumers (e.g., CL-08 CDS and designated governance automations).
  • Consumers must verify active 42 CFR Part 2 consent for the referenced chart before processing protected fields.
  • Consumer access to this event payload must be audit-logged with the same rigor as direct cl_pdmp_queries access.
Stub payload (to be finalized when implemented): 
interface PdmpQueryCompletedPayload {
  query_id: string;           // UUID of cl_pdmp_queries record
  organization_id: string;
  chart_id: string;           // 42 CFR Part 2 protected
  queried_by: string;         // user UUID
  gateway_provider: string;   // 'pmp_gateway' | 'bamboo_health' | 'arizona_hie'
  patient_match_found: boolean; // 42 CFR Part 2 protected
  interstate_query: boolean;
  states_queried: string[];
  // Pre-computed, non-identifying summary fields for downstream CDS without secondary PHI query:
  risk_level: 'none' | 'low' | 'moderate' | 'high' | 'critical';
  high_risk_indicators: string[]; // e.g. ['multiple_prescribers', 'high_opioid_dose']
  summary_text?: string;
  evaluation_time: string;    // ISO timestamp
}

​
Security and RLS

  • Permission keys (PF-30): cl.pdmp.queries.view, cl.pdmp.queries.create, cl.pdmp.configuration.manage (see spec for usage).
  • RLS enabled on cl_pdmp_queries and cl_pdmp_configuration with organization isolation.
  • Policies: org isolation, prescriber access, delegate access, admin access.
  • All policies MUST use SECURITY DEFINER helpers (no direct queries to RLS-protected tables); UPDATE policies MUST include WITH CHECK (constitution §5.2.4).
  • Audit (minimalism): Application logs MUST use only non-PII/PHI identifiers: query id, organization_id, timestamp, and optionally gateway_transaction_id for correlation. Do NOT log patient or prescriber identifiers. Retain audit records per HIPAA (e.g. 6-year retention) where applicable. INSERT and updates to prescriber_attestation / results_reviewed_at form the A.R.S. § 36-2606 evidence trail.