EHR Integration Patterns
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