What does HL7 to FHIR conversion involve?
HL7 to FHIR conversion turns HL7 v2 messages (ADT, ORU, ORM and others) or C-CDA documents into FHIR R4 resources. Start from HL7’s Version 2 to FHIR Implementation Guide (1.0.0, STU 1): PID becomes Patient, PV1 Encounter, ORC and OBR ServiceRequest and DiagnosticReport, OBX Observation. The mapping is the easy part. Most of the effort goes on terminology (local codes to LOINC, SNOMED CT and UCUM), identifiers, time zones, duplicates and validating against the target profile, such as US Core.
A converter that runs is not the same as one that tells the truth
Most teams can get a demo converter working in a week. Point Microsoft’s Liquid templates or a Mirth channel at an ADT feed and FHIR JSON comes out. The trouble starts later: a corrected lab result arrives as a second Observation instead of replacing the first, an admission time shifts by five and a half hours, a local test code nobody mapped lands in a field that downstream analytics reads as LOINC, and the same patient appears three times because two feeds use different assigning authorities.
This guide is the engineering view of HL7 to FHIR conversion as of November 2026. It covers what HL7’s official mapping guide gives you and what it leaves to you, a segment-to-resource table, the data types that quietly break things, terminology, identity and idempotency, transaction Bundles, Z-segments, target profiles (US Core, IPS and India’s ABDM), validation, C-CDA documents, and the main tools with their current status. There is a worked ADT^A01 example with the resulting FHIR, and an ORU^R01 walkthrough.
If you would rather hand the work over, we build conversion pipelines as part of our FHIR interoperability and HL7 and EDI integration services, usually on an engine your team already runs. Background on the two standards is in our HL7 vs FHIR guide.
What changes when a v2 message becomes FHIR
An HL7 v2 message reports an event: a patient was admitted, a result was released, an order was cancelled. FHIR stores state: this is the patient, this is the encounter and its current status, these are the results. Converting one into the other is not a format change. Every message has to be applied to what the receiving server already holds, which is why identity, ordering and corrections matter more than field mapping.
C-CDA is different again. A Continuity of Care Document is a snapshot of a record at a point in time, with human-readable narrative and coded entries side by side. Ten documents from the same clinic will contain the same allergy ten times. Converting documents is mostly about extraction and de-duplication.
HL7’s Version 2 to FHIR Implementation Guide: what it gives you
HL7 published the HL7 Version 2 to FHIR Implementation Guide as release 1.0.0, STU 1, on 7 October 2025. It is the current published version, after ballots in 2020 and January 2024. What it contains:
- Four kinds of map: message structures (ADT_A01, ORU_R01, VXU_V04 and others), segments, data types and code systems. The authors started from v2.9 but say the guide is not tied to one v2 version.
- Machine-readable form: the maps are authored as CSV spreadsheets and published as FHIR ConceptMap resources, with conditions written in a simple computable syntax and FHIRPath, so an engine can load them as a starting point.
- Target: FHIR R4 base resources. The guide does not choose a profile such as US Core for you.
- Implementation considerations worth reading before you write a line of code: every resource in the output Bundle needs a unique id, receivers should read no meaning into those ids, de-duplication should use identifiers, segment action codes need your own rules, and constraints from local v2 guides are out of scope. The US v2.5.1 immunisation guide’s extra OBX segments are its own example.
Treat the guide as the reference for “where does this field go”, not as a converter. It is a specification; you still need a runtime, terminology services, identity rules and tests.
HL7 v2 to FHIR mapping by segment
The targets below are the ones the guide’s segment maps name. The right-hand column is what tends to go wrong in real feeds.
| Segment | FHIR R4 target(s) in the guide | Watch for |
|---|---|---|
| MSH message header | Bundle, MessageHeader, Provenance | MSH-10 control ID is your replay and duplicate key. MSH-4 sending facility becomes one Organization reused across the Bundle. |
| EVN event type | Provenance | EVN-2 is when the event was recorded, EVN-6 when it happened. Order messages by the right one. |
| PID patient identification | Patient, also Account | PID-3 repeats, each with its own assigning authority. PID-2 and PID-4 are deprecated but still sent by older systems. |
| PD1 additional demographics | Patient, Observation | Adds to the same Patient as PID; do not create a second one. |
| NK1 next of kin | Patient.contact or RelatedPerson | Pick one rule for the whole interface and write it down. |
| PV1 / PV2 patient visit | Encounter, plus Location and Practitioner references | PV1-19 visit number is missing or reused in many outpatient feeds. PV1-2 patient class drives Encounter.class. |
| ORC / OBR order and request | ServiceRequest, DiagnosticReport, Specimen | Placer (ORC-2) and filler (ORC-3) numbers become separate identifiers. OBR-25 result status drives the report status. |
| OBX observation | Observation; DocumentReference for embedded documents | OBX-2 value type decides value[x]. OBX-6 units need UCUM. OBX-11 carries corrections. |
| NTE notes | Annotations on ServiceRequest or Observation; DocumentReference | Comments that change clinical meaning (“haemolysed sample”) must stay attached to the right result. |
| AL1 / IAM allergies | AllergyIntolerance | AL1-3 is often free text or a local code; severity and reaction are optional and inconsistent. |
| DG1 diagnosis | Condition, Encounter.diagnosis, EpisodeOfCare | DG1-6 diagnosis type (admitting, working, final) decides how the Condition should be categorised. |
| PR1 procedures | Procedure | Code system varies by country: CPT, ICD-10-PCS, SNOMED CT or local. |
| IN1 insurance | Coverage, with the payer as an Organization | Subscriber relationship and policy numbers are often in Z-segments instead. |
| RXA administration | Immunization | CVX codes, lot numbers and completion status. |
| SPM specimen | Specimen | Missing in v2.3-era feeds, where specimen data sits in OBR. |
| MRG merge | Account, in the guide | A patient merge (ADT^A40) is a workflow, not a field map: decide how Patient.link and existing references are handled. |
Data types: where conversions quietly go wrong
- CX to Identifier. CX.4, the assigning authority, has to become a URI in Identifier.system, so keep a table that turns each namespace (“GENHOSP”, “LABSYS”) into a stable URI or OID. CX.5, the identifier type, maps to Identifier.type through v2 table 0203 (MR, VN, NH and so on). Get this wrong and the same patient becomes several.
- XPN to HumanName. Family name, given names and prefix map directly. XPN.7, the name type, goes through a vocabulary map to HumanName.use. Several names in PID-5 are normal; keep them all.
- XAD and XTN. Addresses map to Address. For phone numbers, v2.5 and later put the country, area and local number in separate XTN components, so do not rely on the deprecated first component.
- CWE and CE to CodeableConcept. Each triplet (code, text, coding system) becomes a Coding, and the alternate triplet becomes a second Coding. Map coding system names to URIs: LN to http://loinc.org, SCT to http://snomed.info/sct, and local systems to a URI you own. Never drop the original code.
- TS and DTM to dateTime or instant. v2 timestamps take the form YYYYMMDDHHMMSS with an optional fraction and an optional offset. FHIR’s dateTime requires a time zone whenever hours and minutes are present. If the sender omits the offset, the converter must apply the sender’s zone with its daylight-saving rules; guessing UTC moves every event. Keep the precision too: a date-only value stays a date, not midnight.
- NM and SN to Quantity, Range or Ratio. Results such as “<5” or “1:320” need a comparator, a range or a ratio, not a string.
- XCN to Practitioner. XCN.1 is the ID and XCN.9 its assigning authority, such as an NPI in the US. Create one Practitioner per person and reuse it: the guide notes that the attending doctor in PV1-7 is often also the ordering provider in ORC-12.
Terminology: local codes to LOINC, SNOMED CT and UCUM
Terminology is where most of the calendar time goes, because a clinician or lab lead has to approve every mapping. Plan it as its own workstream, starting in week one.
- Lab tests: local order and result codes to LOINC. Order codes and result codes are different lists; a panel maps to one LOINC code and each analyte to another. US Core expects LOINC for laboratory result codes.
- Problems, procedures, specimens and body sites: SNOMED CT where the target profile asks for it, ICD-10 where billing does.
- Units: free-text units to UCUM, for example “mg/dl” to mg/dL and “10^3/uL” to 10*3/uL. FHIR’s vital-signs profiles require UCUM, and most receivers expect it for lab values too.
- v2 tables: abnormal flags (table 0078) to Observation.interpretation; result status (table 0085) to Observation.status, with F as final, P as preliminary, C as corrected and W (wrong patient) as entered-in-error; patient class (table 0004) to Encounter.class.
Keep the maps as ConceptMap resources in version control and look codes up through a terminology service or a $translate call, not hard-coded if-statements. Send both codings, local and standard, so a reviewer can always see where a value came from. Codes with no approved mapping go to a review queue, not into production with a guess.
Identity, duplicates and idempotency
A converter will see the same message twice: engines retry, senders resend, and someone will replay a day of traffic after an outage. Design for it.
- Conditional create and update. Write Patients with
PUT Patient?identifier=system|value, orPOSTwith an If-None-Exist header, so a second admission for the same MRN updates rather than duplicates. The same pattern works for Encounter (visit number), ServiceRequest (placer and filler numbers) and DiagnosticReport (filler order number). - Stable keys for results. Key an Observation on filler order number plus OBX-3 code plus OBX-4 sub-ID, not on OBX-1, which senders renumber in corrected messages.
- Out-of-order messages. Compare event times before applying an update, so an A08 delayed in a queue cannot overwrite a newer discharge.
- Merges, cancels and deletes. ADT^A40 needs a Patient.link rule and a plan for references to the retired record; A11 (cancel admit) and A13 (cancel discharge) change Encounter status rather than delete anything.
- Patient matching is not the converter’s job. Never match on name and date of birth inside the transform. Send identifiers through, and let a master patient index decide that two records are one person.
Transaction Bundle, batch or one resource at a time?
| Output | Behaviour | Use it when |
|---|---|---|
| Transaction Bundle | All entries succeed or none do. Internal references use urn:uuid fullUrls, resolved by the server; conditional URLs find existing records. | Our default: one v2 message, one transaction, so a half-applied admission never exists. |
| Batch Bundle | Each entry succeeds or fails on its own. Azure’s $convert-data returns this type. | Bulk historical loads where partial success is acceptable and failures are reprocessed. |
| FHIR message Bundle | MessageHeader first, sent to a $process-message endpoint. | Only when the receiver is built for FHIR messaging, which few servers are. |
| Individual REST calls | One request per resource, in your own order. | Very small feeds. You have to handle partial failures yourself. |
Keep the original v2 message, unchanged, in an archive keyed by MSH-10, and point a Provenance resource at it. When someone questions a value two years later, you can show exactly what arrived.
Z-segments and local extensions
Almost every production feed carries Z-segments or uses standard fields in non-standard ways. Inventory them from real samples, not the interface specification, then decide field by field: map to a standard element, define a FHIR extension with a StructureDefinition at a URL you control, or drop it with the receiving team’s agreement in writing. Do not hide Z-segment data in free-text notes; nobody will find it, and the validator cannot check it. Publish your extension definitions in the same package as your profiles so validation knows about them.
Choosing the target profile: US Core, IPS or ABDM
| Target | Current version (7 Nov 2026) | Use it for |
|---|---|---|
| US Core | 9.0.0, published May 2026, aligned to USCDI v6. ONC certification still uses US Core 6.1.0 and USCDI v3 as the baseline, required since 1 January 2026; newer pairs up to 9.0.0 and USCDI v6 are allowed through ONC’s Standards Version Advancement Process. | Data that US certified EHRs, payers or patient-access apps will read. Match the version your receiving server states in its CapabilityStatement, not the newest one. |
| International Patient Summary (IPS) | 2.0.1, an errata release of STU 2, June 2026 | Cross-border or cross-organisation patient summaries as Composition-based document Bundles. |
| ABDM FHIR guide (India) | 6.5.0 from NRCeS, May 2025 | Health records shared through India’s Ayushman Bharat Digital Mission: DiagnosticReportRecord, OPConsultRecord, DischargeSummaryRecord and others, each a document Bundle. See our ABDM integration page. |
| Base FHIR R4 only | 4.0.1 | An internal analytics store that only your own team reads. Even then, constrain it with your own profiles. |
Validating converted FHIR
- Structural and profile validation. Run the HL7 FHIR Validator (validator_cli.jar, updated several times a month) with your target implementation guide packages loaded, or call $validate on HAPI FHIR or a cloud FHIR service. Errors fail the build; warnings are tracked and reduced.
- A corpus of real messages. Collect a few hundred de-identified production messages covering every trigger event, every OBX value type and the known oddities. Convert the whole corpus on every change, in CI.
- Content checks. Validation proves the shape, not the meaning. Compare source and output field by field for a sample, and have a clinician review a random set of converted results, including corrected ones.
- Counts. Messages in, resources out, rejects and review-queue items per day, on a dashboard someone looks at.
- Server conformance. If the converted data is served through a US certified API, Inferno test kits check the API and profiles end to end. They test the server, so they complement the steps above rather than replace them.
C-CDA to FHIR conversion
HL7’s C-CDA on FHIR Implementation Guide reached 2.0.0 (STU 2) in June 2026. That release dropped the document profiles and is now a mapping guide, with pages in both directions, C-CDA to FHIR and FHIR to C-CDA, for allergies, encounters, immunisations, medications, notes, participations, patient, problems, procedures, results, social history and vital signs, with ConceptMaps for the vocabularies. Start there rather than inventing your own section maps.
What makes documents harder than messages:
- Repetition. Every CCD restates the whole problem and medication list. Match entries across documents on their entry IDs and codes before creating anything, or the record fills with copies.
- Narrative versus entries. The text a clinician reads and the coded entries can disagree, and some sections are narrative only. Keep the original document as a DocumentReference with the XML attached, and convert the coded entries.
- nullFlavor and templates. Missing values are explicit (nullFlavor), and the same section can appear under different template versions. The converter must recognise both.
- Document or discrete data? Some receivers want a FHIR document (a Composition-based Bundle); most clinical stores want discrete AllergyIntolerance, Condition and MedicationStatement resources. Decide per receiver.
HL7 to FHIR tools compared (status on 7 November 2026)
| Tool | What it does | Status checked 7 Nov 2026 | Fits when |
|---|---|---|---|
| Mirth Connect or Open Integration Engine | Integration engine: MLLP listeners, queues, retries, JavaScript transformers; you write the FHIR mapping, often with HAPI FHIR classes. | Mirth Connect is commercial from 4.6; 4.5.2 was the last open-source release. The community fork, Open Integration Engine, released 4.7.0 on 21 October 2026 under MPL-2.0. | You already run v2 interfaces on it. Conversion becomes one more channel with the same monitoring. See Mirth Connect services and Mirth Connect migration. |
| Microsoft FHIR-Converter | Open-source engine with Liquid templates: HL7 v2 (templates based on v2.8), C-CDA, JSON and STU3 to R4, plus FHIR to HL7 v2 in preview. | MIT licence, not archived. Last tagged release v7.0, June 2024; maintenance commits continue (November 2026). Its container API is still labelled preview. | You want templates as a starting point and will own and test your copy of them. |
| Azure Health Data Services $convert-data | The same Liquid templates as an operation on the FHIR service; returns a batch Bundle that you then load. | Documented (August 2026). Microsoft says its default templates are unsupported and not intended for production; host your own copy in Azure Container Registry. Azure API for FHIR was retired on 30 September 2026. | Your FHIR store is already on Azure and you will maintain your own templates. |
| Google Cloud Healthcare API | HL7v2 stores ingest messages through an MLLP adapter, parse them and publish Pub/Sub notifications; FHIR stores hold the result. | The HL7v2 store does not convert to FHIR by itself. Google’s reference HL7v2-to-FHIR samples use Whistle 1, which Google marks as an unsupported legacy version; its managed route is the Healthcare Data Engine solution. | You are on Google Cloud and will build or buy the mapping layer. |
| AWS HealthLake | Managed FHIR R4 data store with SMART on FHIR and bulk export. | Its Data Transformation Agent (preview) converts C-CDA and CSV to FHIR R4. HL7 v2 is not on its list, so v2 needs your own pipeline in front. | You are on AWS, especially for C-CDA. Pair it with an engine or code for v2. |
| LinuxForHealth hl7v2-fhir-converter | Java library with YAML templates, originally from IBM. | Apache-2.0. Last release 1.1.1, September 2024; occasional commits (February 2026). | A Java team wants a library to extend, and accepts a slow upstream. |
| HAPI FHIR and HAPI HL7v2 | Java libraries: v2 parsing, the FHIR R4 model, a validator and a full FHIR server. | HAPI FHIR 8.x, released every few weeks; HAPI HL7v2 2.6.0 (February 2025). | You want full control in code, or a self-hosted FHIR server. |
None of these removes the work in the earlier sections. Templates and cloud operations save the first few weeks of field mapping; terminology, identity rules, Z-segments and validation are yours whichever tool you pick. We are not a reseller or partner of any vendor in this table.
Worked example: ADT^A01 to Patient and Encounter
Illustrative, not client work. The patient, hospital and identifiers are invented. The sender does not include a time-zone offset, and the interface specification says it is in India Standard Time.
MSH|^~\&|ADT1|GENHOSP|FHIRCONV|GENHOSP|20261107083015||ADT^A01^ADT_A01|MSG000123|P|2.5.1
EVN|A01|20261107083000
PID|1||884512^^^GENHOSP^MR||Sample^Asha^K^^Ms||19880614|F|||12 Lake View Road^^Chennai^TN^600017^IND^H||^PRN^PH^^91^44^24345678
PV1|1|I|WARD3^305^B^GENHOSP||||D4521^Iyer^Anand^^^Dr^^^GENHOSP|||MED|||||||||V77881^^^GENHOSP^VN|||||||||||||||||||||||||20261107082500The converter produces one transaction Bundle. Abridged: in production we also create Practitioner and Location resources, a Provenance for the message, and reference them.
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:1d0b6c2e-5f3a-4c8e-9a71-2b6f0e4d8a10",
"resource": {
"resourceType": "Patient",
"identifier": [{
"type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" }] },
"system": "https://genhosp.example.org/fhir/sid/mrn",
"value": "884512"
}],
"name": [{ "use": "official", "family": "Sample", "given": ["Asha", "K"], "prefix": ["Ms"] }],
"telecom": [{ "system": "phone", "value": "+91 44 2434 5678", "use": "home" }],
"gender": "female",
"birthDate": "1988-06-14",
"address": [{ "use": "home", "line": ["12 Lake View Road"], "city": "Chennai",
"state": "TN", "postalCode": "600017", "country": "IND" }]
},
"request": { "method": "PUT",
"url": "Patient?identifier=https://genhosp.example.org/fhir/sid/mrn|884512" }
},
{
"fullUrl": "urn:uuid:7c4e2a9b-0d6f-4b3e-8f15-a9c2d7e61b42",
"resource": {
"resourceType": "Encounter",
"identifier": [{
"type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "VN" }] },
"system": "https://genhosp.example.org/fhir/sid/visit",
"value": "V77881"
}],
"status": "in-progress",
"class": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "IMP",
"display": "inpatient encounter" },
"subject": { "reference": "urn:uuid:1d0b6c2e-5f3a-4c8e-9a71-2b6f0e4d8a10" },
"participant": [{
"type": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "ATND" }] }],
"individual": { "display": "Dr Anand Iyer (D4521)" }
}],
"period": { "start": "2026-11-07T08:25:00+05:30" },
"location": [{ "location": { "display": "WARD3, room 305, bed B" } }]
},
"request": { "method": "PUT",
"url": "Encounter?identifier=https://genhosp.example.org/fhir/sid/visit|V77881" }
}
]
}The decisions behind it:
- GENHOSP in CX.4 became a URI from the namespace table, and MR and VN became Identifier.type codes from table 0203.
- PV1-2 “I” became Encounter.class IMP. An A01 means the patient is in hospital, so the status is in-progress.
- PV1-44 had no offset, so the configured zone was applied: 08:25 became 08:25:00+05:30, not 08:25 UTC. A US sender would need its zone’s daylight-saving rules as well.
- Both resources use conditional PUTs, so replaying MSG000123 changes nothing, and a later A08 updates the same records.
- The Encounter points at the Patient through the urn:uuid; the server swaps in the real id when it commits the transaction.
ORU^R01 to DiagnosticReport and Observations
A lab result message follows the same pattern with more decisions per field. OBR becomes a DiagnosticReport, keyed on the filler order number, with its code from OBR-4 (a LOINC panel code after terminology mapping) and its status from OBR-25. Each OBX becomes an Observation referenced from DiagnosticReport.result:
- OBX-2 picks the value type: NM to valueQuantity with a UCUM unit from OBX-6, CWE to valueCodeableConcept, ST or TX to valueString, SN to a Quantity with a comparator or a Range, and ED (an embedded PDF) to an attachment in DiagnosticReport.presentedForm or a DocumentReference.
- OBX-7, the reference range, goes to referenceRange; keep the text when it does not parse into numbers. OBX-8 abnormal flags go to interpretation, OBX-14 to effectiveDateTime and OBX-11 to status.
- A corrected result (OBX-11 “C”, OBR-25 “C”) updates the existing Observation found by its key and sets status corrected. It must never create a second result for the same test.
- NTE segments under an OBX become Observation.note on that result, not on the report.
Pitfalls we see most often
- Mapping from the interface specification instead of a week of real messages.
- Treating missing time-zone offsets as UTC.
- Creating a new resource for every message instead of conditional updates, so replays and corrections duplicate data.
- Dropping the original local code once a standard code is found, or sending an unreviewed guess.
- Free-text units in valueQuantity, which fail validation and break graphs.
- Default templates in production with no tests, then a platform update changes the output.
- Assigning authorities that differ between feeds (“GH”, “GENHOSP”, an OID), so one person becomes three Patients.
- No archive of the original message, so nobody can prove what the sender actually said.
- Validating against base FHIR when the receiver enforces US Core or ABDM profiles.
- No review queue: unmappable messages are either silently dropped or loaded with gaps.
How a conversion project runs, with effort
Illustrative, not client work: one hospital’s ADT and ORU feeds converted into a FHIR server that enforces US Core, on the hospital’s existing integration engine. Effort is in engineer-days and does not include the clinical reviewer’s time for terminology sign-off.
| Phase | What happens | Typical effort |
|---|---|---|
| Samples and scope | A week of de-identified messages per feed, trigger events listed, target profiles and server confirmed | 2–4 engineer-days |
| Mapping specification | Field-level maps based on the v2-to-FHIR guide, identity and ordering rules, Z-segment decisions | 4–6 engineer-days |
| Terminology | Local test codes to LOINC, units to UCUM, flags and statuses; ConceptMaps in version control | 5–10 engineer-days |
| Build | Engine channels or service, transaction Bundles, archive and Provenance, review queue, alerts | 8–14 engineer-days |
| Validation | Validator in CI, corpus replay, field-by-field comparison, clinician spot check | 4–6 engineer-days |
| Parallel run and go-live | Live traffic converted alongside the existing flow, daily comparison, then cutover | 3–5 engineer-days |
Total: roughly 26–45 engineer-days over six to eight weeks. What stretches it: a long tail of local test codes, feeds with no stable visit number, and a receiving server that enforces profiles nobody tested against early.
HL7 to FHIR conversion packages
Typical effort in engineer-days. We confirm a fixed price per phase after reviewing your sample messages or documents.
Mapping specification
The problem
You have feeds and a target, but no agreed field-level mapping, and every developer reads the v2 specification differently.
How we do it
We analyse a week of your real messages, write the segment and data type maps against HL7’s v2-to-FHIR guide and your target profiles, set the identity and ordering rules, list the terminology gaps and Z-segment decisions, and agree it all with the receiving team. Typical effort: 5–10 engineer-days per message family such as ADT or ORU.
What you get
- Mapping spreadsheet per message type
- Identity, ordering and correction rules
- Terminology gap list
- Z-segment and extension decisions
Conversion pipeline for one feed
The problem
You need ADT, lab results or orders arriving in a FHIR server reliably, not a demo that breaks on the first corrected result.
How we do it
We build the conversion on your engine (Mirth Connect, Open Integration Engine or another) or as a small service: transaction Bundles with conditional updates, ConceptMaps, an archive of original messages, a review queue, validation in CI and alerts. Typical effort: 15–30 engineer-days per feed, including the parallel run.
What you get
- Working conversion in production
- Validator and replay corpus in CI
- Review queue for unmapped codes
- Runbook and handover
C-CDA to FHIR
The problem
You receive CCDs, discharge summaries or referral notes and want discrete, deduplicated FHIR data, not stored XML.
How we do it
We follow the C-CDA on FHIR 2.0.0 mappings for the sections you need, keep each original document as a DocumentReference, match repeated entries across documents and validate against your target profiles. Typical effort: 15–35 engineer-days for a CCD plus one or two other document types.
What you get
- Section-level mapping
- De-duplication across documents
- Originals kept and linked
- Validated output
Converter review and repair
The problem
A converter is already live, built on default templates or by a team that has moved on, and it produces duplicates, wrong times or validation errors.
How we do it
We replay a sample of your traffic through it, validate the output, compare it field by field with the source, and fix the worst problems first: time zones, conditional updates, corrections, units and unmapped codes. Typical effort: 5–12 engineer-days.
What you get
- Findings with examples from your data
- Fixes for the top issues
- Replay corpus you keep
- Validation in CI
Specifications and tools behind this guide
Versions and status were read from HL7, regulator and vendor sources on 7 November 2026. Check them again before you start: several change every few months.
HL7 Version 2 to FHIR 1.0.0
STU 1, published 7 October 2025. Message, segment, data type and code system maps, published as ConceptMaps, plus implementation considerations.
C-CDA on FHIR 2.0.0
STU 2, June 2026. Document profiles and two-way mapping pages for twelve clinical domains, with vocabulary ConceptMaps.
US Core 9.0.0, IPS 2.0.1, ABDM 6.5.0
The usual targets. US certification still has US Core 6.1.0 and USCDI v3 as its baseline, with newer versions allowed.
HL7 FHIR Validator and Inferno
The command-line validator for structure and profiles; Inferno test kits for US certified API conformance.
Mirth Connect and Open Integration Engine
Where most v2 traffic already flows. Mirth is commercial from 4.6; the open-source fork released 4.7.0 in October 2026.
FHIR-Converter, $convert-data, HealthLake
Liquid templates (MIT, last tagged release June 2024), Azure’s operation built on them, and AWS’s C-CDA and CSV agent in preview.
Tools we use alongside it
- Open Integration Engine
- Mirth Connect
- HAPI FHIR
- HAPI HL7v2
- HL7 FHIR Validator
- Microsoft FHIR-Converter
- Azure Health Data Services
- Google Cloud Healthcare API
- AWS HealthLake
- Inferno
Facts, versions and vendor details checked 7 November 2026.
How a conversion engagement runs
For one feed. More feeds add build time, not more stages.
Samples and target
De-identified sample messages or documents, the receiving server and its profiles, and the people who will sign off terminology.
Mapping specification
Field-level maps, identity and correction rules, Z-segment decisions and a terminology gap list, agreed with the receiving team.
Build and terminology
The conversion on your engine or as a service, ConceptMaps reviewed by your clinician, validation and replay in CI.
Parallel run and handover
Live traffic converted alongside the current flow, daily comparison, cutover, then a runbook and handover to your team.
HL7 we run in our own products
We operate software that sends and receives HL7, so feed quirks, units and engine failures are problems we deal with ourselves.
PathLab Software
Lab information system — sample to signed WhatsApp report Our lab information system takes analyser results over HL7 v2 and ASTM through a connector on the lab PC, so result values, units, flags and reference ranges are part of its everyday work. Visit pathlabsoftware.com
Radiatus OneHealth
Certified OpenEMR plus 25 practice modules, with nothing to migrate Radiatus OneHealth hosts certified OpenEMR unmodified and includes an HL7 engine monitoring module, because a conversion pipeline nobody watches is the one that fails quietly. Visit openemr.radiatus.comGuides and related pages
Guides
Technologies
Glossary
Where we work
HL7 to FHIR conversion: common questions
Parse each message, map its segments to FHIR R4 resources using HL7’s Version 2 to FHIR Implementation Guide as the reference (PID to Patient, PV1 to Encounter, OBR to DiagnosticReport, OBX to Observation), translate local codes to standard terminologies, and load the result as a transaction Bundle with conditional updates so replays and corrections do not create duplicates. Validate the output against your target profile before it goes live.
Yes. HL7 published the Version 2 to FHIR Implementation Guide as release 1.0.0, STU 1, in October 2025. It maps message structures, segments, data types and code systems to FHIR R4 and publishes the maps as ConceptMap resources. It is a reference specification, not a converter, and it targets base FHIR rather than profiles such as US Core.
Use the mapping pages in HL7’s C-CDA on FHIR Implementation Guide, which reached 2.0.0 in June 2026, for the sections you need. Keep the original document as a DocumentReference, convert the coded entries to discrete resources, and match repeated entries across documents so the same allergy or medication is not loaded many times.
You can, but treat the templates as your own code. Microsoft says the default templates for $convert-data are unsupported and not intended for production, and recommends hosting your own copy. The open-source FHIR-Converter is MIT-licensed and still maintained, though its last tagged release was in June 2024. Either way you need your own tests, terminology and identity rules.
Mirth Connect, and its open-source fork the Open Integration Engine, give you listeners, queues, retries and transformers, but not a ready-made HL7 to FHIR map. You write the mapping in a channel, often using HAPI FHIR classes, following the v2-to-FHIR guide. Its strength is that conversion runs beside your existing interfaces with the same monitoring.
FHIR requires a time zone on any dateTime that includes hours and minutes, while HL7 v2 makes the offset optional. If the sender omits it, apply the sender’s configured zone with its daylight-saving rules. Never assume UTC, and keep date-only values as dates rather than midnight timestamps.
For one feed such as lab results, our typical range is 15 to 30 engineer-days including a parallel run, over about five to seven weeks. Terminology sign-off by your clinician or lab lead often sets the pace. We confirm a fixed price per phase after reviewing your sample messages.
The one your receiver enforces. In the US that is usually a US Core version; certified EHR APIs have US Core 6.1.0 as their baseline, and US Core 9.0.0 is the latest. Cross-border summaries use the International Patient Summary, and Indian records shared through ABDM use the NRCeS FHIR guide, currently version 6.5.0.
Have HL7 or C-CDA data that needs to become FHIR?
Tell us the feeds or document types, the receiving FHIR server and the profile it enforces. A senior integration engineer will reply with the questions that decide the scope and a typical effort range.






Compliance-first delivery