EHR Integration Patterns

Executive Summary

The Electronic Health Record (EHR) is the primary data source for clinical AI and the primary system of record into which AI outputs are written. EHR integration for AI requires mastering three distinct protocols: FHIR R4 for structured data access, HL7 v2 for legacy ADT event feeds, and CDS Hooks for inline clinical decision support at the point of care. Each protocol has distinct authorization patterns, data models, and integration constraints. This chapter provides the integration patterns for connecting AI systems to EHR infrastructure, with working examples from the HMS scenario.

Learning Objectives

  • Design FHIR R4 read and write operations for clinical AI context retrieval and result persistence
  • Implement CDS Hooks services that meet the 5-second EHR timeout requirement
  • Handle SMART on FHIR authorization for AI-powered clinical applications
  • Map HL7 v2 ADT messages to Kafka events for real-time clinical AI triggers

Business Problem

A Reference Healthcare Organization deploying clinical decision support AI faces a fundamental integration problem: the clinical data needed to inform AI recommendations lives in the EHR (patient demographics, diagnoses, medications, lab results, encounters), but the AI inference layer runs outside the EHR. This data must be retrieved in real time, used to augment the AI prompt, and the AI's output must be written back to the EHR in a format that clinicians can access within their normal workflow.

FHIR R4 is the standard solution for this read/write integration. CDS Hooks is the standard mechanism for surfacing AI recommendations inline within the EHR clinical workflow. HL7 v2 ADT feeds are the legacy (but still dominant) mechanism for real-time event notification from inpatient EHR systems.

Enterprise Considerations

FHIR versioning: FHIR R4 is the current required version for US healthcare AI integrations (US Core Implementation Guide). FHIR R4B and R5 introduce breaking changes; confirm the EHR vendor's FHIR version before building integration code.

CDS Hooks performance budget: The EHR imposes a hard 5-second timeout on CDS Hook calls. AI systems must stay well within this budget: FHIR prefetch reduces round-trips, semantic caching eliminates LLM calls for repeated clinical scenarios, and timeout handling ensures empty cards are returned rather than EHR workflow failures.

SMART on FHIR scopes: Request the minimum necessary FHIR scopes. Clinical AI systems frequently over-request scopes "to be safe." Over-broad FHIR scopes are a HIPAA minimum-necessary violation. See Identity and Access for SMART scope guidance.

Common Mistakes

1. FHIR requests in series during CDS Hook. Making FHIR API calls sequentially within a CDS Hook (Patient → Conditions → Medications → Labs → Allergies) consumes 1–2 seconds per call and will timeout. Always execute parallel FHIR requests with asyncio.gather.

2. Not handling FHIR prefetch failures. If the EHR fails to populate prefetch resources (network error, permission), the CDS Hook receives null prefetch. The hook must detect this and fall back to direct FHIR calls or return empty cards.

3. Writing AI drafts to EHR without docStatus: "preliminary". An AI draft written with docStatus: "final" appears to clinicians as a finalized document. All AI-generated documents must use docStatus: "preliminary" pending physician review and signature.

Key Takeaways

  • FHIR R4 parallel requests are required for CDS Hooks performance within the 5-second EHR timeout
  • AI-generated EHR documents must use docStatus: "preliminary" — never write as final
  • CDS Hooks must return empty cards on timeout, never block the EHR workflow with errors
  • HL7 v2 ADT messages are the dominant real-time event feed for inpatient AI triggers; bridge them to Kafka for scalable AI event consumption
  • SMART on FHIR scopes must be minimum-necessary; over-broad scopes are a HIPAA violation

Further Reading