FHIR Implementation: A Phased Playbook

"FHIR implementation" covers several kinds of project: exposing a FHIR API on top of an existing system, standing up a FHIR server as a clinical data repository, building an app that consumes EHR FHIR APIs, or meeting a regulatory requirement such as the CMS payer API rules. The phases below apply to all of them, though the weight of each phase changes. A consumer app spends more time on EHR-specific testing; a payer API program spends more on data mapping and conformance.

This playbook assumes you know the basics covered in What is FHIR?. If you are weighing whether to do the work in-house, see the FHIR implementation service page for what external partners typically take on.

Write down concrete use cases before any technical decision: who needs which data, in what workflow, how fresh, and with what write-back. "Share clinical data with partners" is not a use case; "a care-management app reads active problems, medications and the last 12 months of lab results for attributed members daily" is.

• Inventory source systems, existing HL7 v2 and CDA interfaces, and who owns each.
• Identify regulatory drivers (ONC certification, CMS-9115-F, CMS-0057-F, national programs) and their deadlines.
• List counterpart systems and confirm which FHIR versions and APIs they actually expose.
• Agree on non-functional requirements: volumes, latency, availability, audit and data retention.
• Define the security model early, including consent, patient matching and app registration.

Your implementation guides define what conformance means, so pick them deliberately. In the US, US Core is the baseline for clinical data, and other IGs layer on top of it: SMART App Launch for authorization, Bulk Data Access for population export, and the Da Vinci and CARIN guides for payer use cases. Outside the US, start from your country's national base profiles.

Pin specific IG versions in your requirements; US Core and others release new versions regularly, and regulations reference particular versions. Choose your FHIR release accordingly: R4 remains the default for regulated exchange. FHIR R4 vs R5 explains when R5 might make sense.

Mapping source data to FHIR profiles is typically the largest single effort. For each profile, document which source table or v2 field fills each must-support element, how missing data is represented, and which transformations apply. Keep the mapping as a versioned, reviewable artifact, not just code.

Terminology deserves its own workstream. US Core binds elements to code systems such as LOINC for lab observations, SNOMED CT for problems and findings, RxNorm for medications, CVX for vaccines and UCUM for units. Source systems frequently use local codes, so you will need concept maps, a process for unmapped codes, and clinical informaticist review. A terminology server that supports operations like $validate-code, $expand and $translate makes this manageable at scale.

Architecture choices at this stage include whether to store data natively in a FHIR server or translate on the fly from source systems (a facade), how to handle identity and patient matching, and how to secure the API. Our FHIR server architecture guide compares the main patterns.

• Implement SMART authorization and scopes alongside the API, not afterward. See FHIR security.
• Publish an accurate CapabilityStatement and keep it in sync with what the server truly supports.
• Add Provenance and audit logging (for example AuditEvent) where your use case or policy requires them.
• Automate validation in CI so every mapping change is checked against the target profiles.

Testing FHIR implementations has three layers: resource validity, API behavior and workflow correctness.

Automated tools confirm structure and protocol; they cannot tell you that a mapped blood pressure is actually the patient's most recent reading. Reserve time for clinical validation with real or realistic data.

Go-live is usually staged: a pilot partner or app, limited data domains, then expansion. Before launch, confirm monitoring of latency, error rates and token failures; runbooks for partner onboarding and credential rotation; and a clear owner for production incidents.

Operations never really end. New IG versions, regulatory updates, EHR upgrades and new partners all trigger change. Budget for it explicitly; the FHIR support and maintenance service page outlines what ongoing support covers.

• Optionality: two systems both "support FHIR" yet populate different elements. Fix it with explicit profiles and must-support agreements.
• EHR variation: each EHR exposes different resources, search parameters and write capabilities. Test against every target, not just one.
• Data quality: FHIR exposes source data quality problems that were hidden inside reports and interfaces.
• Patient matching across organizations remains hard and needs a deliberate strategy.
• Performance: deep _include chains and unbounded searches can overload servers; design queries and paging carefully.
• Skills gaps: teams strong in v2 interfaces or in web APIs, but not both. Pair them or bring in FHIR consulting support.