Arizona CSPMP/PDMP Integration — Integration Contract

​

Cross-Core Integration Matrix

​

Overview

​

Integration Points

​

Adapter Architecture (CL-17-EN-01, #1964)

• Interface: PdmpAdapter.query(input, credentials, config) → PdmpReport + validateConfig(config). Every adapter returns the same normalized PdmpReport; vendor response shapes never leak past the seam. The normalized summary is persisted verbatim to cl_pdmp_queries.results_summary and is the shape PdmpResultsView parses (PdmpResultsSummary). Risk indicators are optional — Arizona’s state-funded Gateway tier returns the Basic PMP report without NarxCare scores.
• Registry: gateway_provider → adapter (pmp_gateway/bamboo_health → Bamboo PMP Gateway adapter; arizona_hie → Contexture slot). Adding a vendor is one registry entry; callers never change.
• Fixture track: a deterministic fixture adapter is selected only when the x-pdmp-fixture: 1 header is present and the runtime is non-prod (server-trusted project ref) — unreachable in production by construction.
• Go-live gates (fail-closed): cl_pdmp_configuration.pdmp_adapter_enabled (default false until vendor contract + BAA land — EN-20) → HTTP 412; no vault credential → HTTP 412; vendor adapter awaiting onboarding → HTTP 501. While gated, prescribers remain compliant via the AWARxE portal link-out + manual attestation (query_method='manual') — A.R.S. § 36-2606(F) is method-agnostic (see specs/cl/research/CL-17-EN-01-RESEARCH.md).
• Statutory map: the three registry slots correspond 1:1 to the three integration routes sanctioned by A.R.S. § 36-2606(I) (subsection (H) from 2026-09-12): direct, statewide HIE, third-party vendor. EMR-vendor integration deadline: 2026-12-31.

​

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, pdmp_adapter_enabled (go-live gate, default false), adapter_options (vendor-specific non-secret options, JSONB).

​

Event Contracts

​

cl_pdmp_query_completed (Planned — Deferred)

• 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.

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.

​

Related Docs

• CL-06 E-Prescribing Integration
• CL-01 Patient Chart Integration
• Spec: CL-17-arizona-cspmp-pdmp-integration.md