What is the difference between HL7 v2 and FHIR?

HL7 v2 is a messaging standard from the 1990s that uses pipe-delimited text messages (ADT, ORU, ORM). It is point-to-point and requires custom mapping at every site. FHIR (Fast Healthcare Interoperability Resources) is a modern REST API standard using JSON/XML resources. FHIR is more developer-friendly, supports OAuth-based auth, and is mandated by the ONC Cures Act for patient-facing data access. New integrations should default to FHIR unless the health system only supports v2.

How long does an EHR integration typically take?

End-to-end, expect 3-9 months from initial conversation to production go-live. The breakdown: 1-2 months for business and security review, 1-2 months for sandbox access and development, 1-2 months for testing and certification, and 1-2 months for deployment and validation. The biggest delays are usually organizational (getting the right people to review and approve), not technical.

Do I need to go through Epic App Orchard to integrate with Epic?

For broad distribution to multiple Epic customers, yes. App Orchard (now called the Epic App Market) certification is the standard path. For a single-site integration with one health system, you can work directly with that system's integration team using their developer portal. The single-site path is faster but does not scale to multiple customers without repeating the process.

What is the ONC Cures Act and how does it affect my integration?

The 21st Century Cures Act (ONC Cures Act) requires certified EHR vendors to implement standardized FHIR APIs for patient data access by 2024. It also prohibits "information blocking," which means EHR vendors and health systems cannot unreasonably restrict data sharing. For you as a health tech PM, this means EHR vendors must provide FHIR API access, and health systems cannot refuse to connect your application without a legitimate reason (security, privacy, or operational concern).

How do I handle data mapping when different health systems use different code systems?

Build a terminology mapping layer. Map incoming codes to your internal canonical model, and maintain mapping tables for ICD-10, SNOMED CT, LOINC, and RxNorm. Use the UMLS (Unified Medical Language System) as a reference for cross-walks between code systems. Accept that some mappings will be imperfect and design your UI to surface unmapped codes for clinical review rather than silently dropping them. ---

Health Data Integration Specification Template

What This Template Is For

Health data integration is where most health tech timelines break down. Connecting to EHR systems, mapping clinical data models, and satisfying interoperability requirements involves regulatory, technical, and organizational complexity that standard API integration specs do not cover. A feature that takes two sprints to build may take two quarters to integrate with a health system's Epic or Cerner instance.

This template gives product managers a structured specification for health data integrations. It covers the interoperability standard (HL7 FHIR, HL7 v2, or proprietary), data mapping, authentication, compliance requirements, and testing strategy. Use it when your product needs to read from or write to EHR systems, health information exchanges (HIEs), or clinical data warehouses. If your product handles protected health information, pair this with the HIPAA Compliance Checklist to cover the regulatory layer.

How to Use This Template

Copy the template sections into your documentation tool.
Start with the Integration Overview. Define which systems you are connecting, what data you need, and which direction data flows.
Fill in the Data Model section with your clinical data mapping. This requires input from both your engineering team and the health system's integration team.
Complete the Authentication and Security section with your infrastructure lead.
Work through the Compliance section with your compliance officer.
Define the Testing Strategy before development begins. EHR sandbox access often has long lead times.
Share the completed spec with the health system's integration team for review. Expect 2-4 rounds of revision.

The Template

Integration Overview

Field	Details
Integration Name	[e.g., Patient Demographics Sync from Epic]
Source System	[e.g., Epic EHR, Cerner Millennium, athenahealth]
Target System	[e.g., Your application name]
Data Direction	[Read-only / Write-back / Bidirectional]
Interoperability Standard	[FHIR R4 / HL7 v2 / CDA / Proprietary API]
Integration Pattern	[REST API / ADT feed / Subscription / Bulk export]
Health System Partner	[Organization name]
Integration Team Contact	[Name, role, email]
Target Go-Live	[Date]
PM Owner	[Name]

Data Requirements

Required Clinical Data Elements

Data Element	FHIR Resource	Source Field	Your Field	Required	Notes
[e.g., Patient name]	[Patient]	[name.given, name.family]	[first_name, last_name]	Yes
[e.g., Date of birth]	[Patient]	[birthDate]	[dob]	Yes
[e.g., MRN]	[Patient]	[identifier (type=MR)]	[mrn]	Yes	[System-specific identifier]
[e.g., Medications]	[MedicationRequest]	[medicationCodeableConcept]	[medications]	Yes	[RxNorm codes]
[e.g., Lab results]	[Observation]	[valueQuantity, code]	[lab_results]	No	[LOINC codes]

Data Volume and Frequency

Metric	Value
Expected patient volume	[e.g., 10,000 patients at launch, growing 20%/quarter]
Data refresh frequency	[Real-time / Hourly / Daily / On-demand]
Average payload size	[e.g., 2-5 KB per patient resource]
Peak request rate	[e.g., 50 requests/second during morning rounding]
Historical data requirement	[e.g., Last 12 months of encounters and results]

Code Systems and Terminology

☐ Document which code systems are used (ICD-10, SNOMED CT, LOINC, RxNorm, CPT)
☐ Map local codes to standard terminologies where they differ
☐ Define fallback behavior when a code is unrecognized
☐ Identify terminology version requirements (e.g., ICD-10-CM 2026 edition)

Authentication and Authorization

Requirement	Implementation
Auth protocol	[SMART on FHIR / OAuth 2.0 / API key / certificate-based]
Client registration	[How your app registers with the EHR's auth server]
Scopes	[e.g., patient/*.read, user/MedicationRequest.read]
Token management	[Token lifetime, refresh strategy]
User context	[Standalone launch / EHR launch / backend service]
Patient consent	[How patient authorization is captured and enforced]

Access Control Checklist

☐ Define which user roles can trigger data exchanges
☐ Implement scope-limited tokens (request only the scopes you need)
☐ Handle token expiration and refresh without user interruption
☐ Log all authentication events for audit purposes
☐ Implement rate limiting to respect the source system's capacity

Compliance Requirements

☐ Confirm BAA is in place with the health system partner
☐ Confirm BAA is in place with any middleware or integration platform vendor
☐ Verify data storage location meets health system requirements (US-only, specific region)
☐ Document PHI data retention and deletion policies
☐ Implement audit logging for all data access and modifications
☐ Confirm encryption at rest and in transit for all PHI
☐ Define data breach notification procedures specific to this integration
☐ Verify compliance with the ONC Cures Act information blocking rules
☐ Document patient data access rights (view, download, transmit via FHIR API)

Error Handling and Resilience

Scenario	Expected Behavior
Source system unavailable	[e.g., Retry with exponential backoff; show cached data with staleness indicator]
Authentication failure	[e.g., Alert ops team; queue requests for retry after re-auth]
Malformed data	[e.g., Log error, skip record, continue processing; alert for manual review]
Rate limit exceeded	[e.g., Backoff per Retry-After header; queue remaining requests]
Partial data response	[e.g., Accept partial data, flag incomplete records for user]
Network timeout	[e.g., 30s timeout; retry once; fail gracefully with user notification]

Resilience Checklist

☐ Implement circuit breaker pattern for source system calls
☐ Define acceptable data staleness (how old can cached data be before it is stale?)
☐ Build a dead letter queue for failed records that need manual review
☐ Implement health check endpoint for monitoring integration status
☐ Define SLA expectations with the health system's integration team

Testing Strategy

Test Type	Environment	Owner	Timeline
Unit tests	Local	Engineering	During development
Integration tests	EHR sandbox	Engineering	[Request sandbox access by this date]
End-to-end tests	Staging with test patients	QA + Clinical	[Date range]
Load tests	Staging	Engineering	[Before go-live]
UAT with clinicians	Production with test patients	PM + Clinical	[Date range]

Sandbox and Test Data Checklist

☐ Request EHR sandbox access (lead time: typically 2-6 weeks)
☐ Confirm sandbox has representative test data (diverse patient demographics, conditions)
☐ Verify test patients do not contain real PHI
☐ Document sandbox limitations (data freshness, supported endpoints, rate limits)
☐ Plan for certification/validation if required (e.g., Epic App Orchard review)

Filled Example: Patient Records API (FHIR R4)

Integration Overview (Example)

Field	Details
Integration Name	Patient Demographics + Medications from Epic via FHIR R4
Source System	Epic EHR (August 2024 version)
Target System	MedTrack Patient Portal
Data Direction	Read-only
Standard	FHIR R4 (HL7 4.0.1)
Pattern	REST API (SMART on FHIR standalone launch)
Health System Partner	Metro Health System (450-bed academic medical center)
Target Go-Live	Q3 2026

Required Data Elements (Example)

Data Element	FHIR Resource	Source Field	Our Field	Required
Patient name	Patient	name[0].given, name[0].family	first_name, last_name	Yes
DOB	Patient	birthDate	date_of_birth	Yes
MRN	Patient	identifier (type=MR, system=urn:oid:1.2.3.4)	mrn	Yes
Active medications	MedicationRequest	medicationCodeableConcept.coding (RxNorm)	medications[]	Yes
Allergies	AllergyIntolerance	code.coding (SNOMED CT)	allergies[]	Yes
Recent labs (90 days)	Observation (category=laboratory)	code (LOINC), valueQuantity	lab_results[]	No

Tips for Health Data Integrations

Start the integration conversation 6 months before you need it. Health system IT teams have long queues, formal review processes, and security assessments. The technical work may take 4 weeks, but the organizational process takes 4 months. Factor this into your product roadmap.

Use FHIR R4 whenever possible. The ONC Cures Act requires certified EHR vendors to support FHIR R4 APIs. Building on FHIR gives you portability across health systems. HL7 v2 integrations are site-specific and require custom mapping at every deployment.

Never assume data quality. Clinical data is messy. Medications may have free-text entries instead of RxNorm codes. Dates may be in unexpected formats. Identifiers may be duplicated or missing. Build your data pipeline to handle inconsistency gracefully. The technical PM guide covers defensive engineering practices.

Budget for certification. Epic App Orchard, Cerner Code, and athenahealth Marketplace all have certification programs with technical and business requirements. Certification can take 2-6 months and may require changes to your application. Start the process early.

Monitor integration health continuously. Set up alerts for error rates, response times, and data staleness. A silent integration failure (data stops flowing but no error is thrown) can go unnoticed for days and affect patient care. Use product metrics to track integration reliability.

Key Takeaways

Start the health system conversation 6 months before your target go-live date
Default to FHIR R4 for new integrations. It is the mandated standard and the most portable
Never assume clinical data quality. Build your pipeline to handle messy, inconsistent data
Budget for EHR certification. It adds 2-6 months to your timeline
Monitor integration health continuously. Silent failures can affect patient care

About This Template

Created by: Tim Adair

Last Updated: 3/4/2026

Version: 1.0.0

License: Free for personal and commercial use

Health Data Integration Specification Template