FHIR Migration Services

Many organizations combine types, for example retiring an STU3 server and moving to a managed R4 service in one program. Treat each as a separate risk register even if they share a timeline.

This is rarely a full replacement. HL7 v2 remains the norm for many real-time hospital feeds, so a typical migration converts v2 messages into FHIR resources for downstream consumers while the source keeps sending v2. Our FHIR vs HL7 v2 guide explains why the two coexist.

• Segment-to-resource mapping: PID to Patient, PV1 to Encounter, OBX to Observation, and so on, including local Z-segments that have no standard equivalent.
• Event semantics: a v2 ADT A08 is an update notification; deciding how that becomes FHIR create, update or a Subscription notification needs deliberate design.
• Document decomposition: C-CDA sections can be stored as a DocumentReference, decomposed into discrete resources, or both. Decomposition creates duplicate-detection work.
• Proprietary API retirement: publish a FHIR alternative, migrate consumers one by one, then deprecate with a firm date.

FHIR R4 (4.0.1) was the first release with normative content, and US Core and the CMS-referenced IGs are built on it. Older implementations face real breaking changes rather than renames. Examples that affect most upgrades:

• MedicationRequest replaced MedicationOrder (from DSTU2), and medication-related resources were restructured.
• AllergyIntolerance and Condition changed `clinicalStatus` and `verificationStatus` from simple codes to CodeableConcepts in R4.
• Profiles must be re-targeted, typically from Argonaut Data Query (DSTU2) or older US Core versions to a current US Core release.
• Search parameters and operations may change name or behavior, which breaks client queries even when data converts cleanly.

{
  "resourceType": "Condition",
  "clinicalStatus": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
      "code": "active"
    }]
  },
  "code": { "coding": [{ "system": "http://snomed.info/sct", "code": "44054006" }] },
  "subject": { "reference": "Patient/example" }
}

If you are weighing a jump beyond R4, see FHIR R4 vs R5; for US regulatory work, R4 remains the target.

Even when both servers run R4, a move can break consumers. Decide up front whether resource IDs must be preserved (clients often store them), whether version history and `meta.lastUpdated` values matter, how references between resources are rewritten if IDs change, and whether search results and paging behave identically. Export via `$export` or paged reads, load via transaction Bundles or the target's bulk import, then reconcile counts and sample records resource type by resource type.

• Which migration types have you delivered, and what were the source and target versions or platforms?
• How do you inventory existing consumers and their dependencies before cutover?
• How do you prove data fidelity: counts, checksums, field-level comparisons, clinical review?
• What is your approach to IDs, references and history when moving servers?
• How do you handle v2 Z-segments and local codes that do not map cleanly?
• What does the rollback plan look like, and has it been tested?

Migration is often the first phase of a broader FHIR implementation; when that is the case, evaluate partners for both.

Migrations suit a fixed-price assessment that inventories sources, consumers and mapping complexity, followed by a delivery phase priced against that inventory. Cost rises with the number of message types or resource types, the proportion of custom extensions and local codes, data volume and history depth, the number of consumers to coordinate, and the length of the parallel-run period.