Saltar al contenido principal

HL7 to FHIR

Category: Healthcare Standards
Node id: hl7-to-fhir

Standards: HIPAA, GDPR, SOC2

Converts HL7v2 messages to FHIR R4 Bundle resources, mapping ADT, ORM, ORU, and other message types to Patient, Encounter, ServiceRequest, Observation and DiagnosticReport resources

What it does​

  • Converts ADT messages to Patient + Encounter resources
  • Converts ORM/OMG messages to Patient + ServiceRequest resources
  • Converts ORU messages to Patient + Observation resources
  • Groups ORU results into one DiagnosticReport per OBR, referencing that OBR's Observations
  • FHIR transaction Bundle generation with POST requests
  • Best-effort conversion for unknown message types
  • Unmapped segment tracking for conversion auditing

Use cases​

  • Convert legacy HL7v2 feeds into FHIR R4 for modern EHR systems
  • Bridge HL7v2 interfaces to FHIR-based analytics platforms
  • Migrate historical HL7 messages to FHIR during system upgrades
  • Enable FHIR-based interoperability for HL7v2-only sending systems

Runtime​

  • Performance tier: fast

Input ports​

NameTypeRequiredDescription
hl7_messagetextYesRaw HL7v2 message string to convert

Output ports​

NameTypeRequiredDescription
resultjsonNoConversion result (fhir_bundle, resources, resource_count, mapping_details, unmapped_segments, source_type, warnings)
successbooleanNoWhether the conversion succeeded

Settings​

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Default time zonedefault_timezonestringNo""IANA time zone (e.g. Europe/Madrid) of HL7 timestamps that carry no UTC offset. Empty, or a local time in a DST gap or overlap of that zone: such timestamps keep only their date (effective) or are omitted (issued), with a warning.

Errors​

CodeDescription
MESSAGE_REQUIREDhl7_message input is missing or empty
UNSUPPORTED_MESSAGE_TYPEMessage type not recognized (best-effort conversion attempted)

Runtime notes​

  • fhir_bundle is a FHIR R4 transaction Bundle with POST requests — ready for FHIR server submission
  • Every entry has a urn:uuid fullUrl; subject, encounter and DiagnosticReport.result reference those fullUrls, so references resolve inside the bundle and the server rewrites them on the transaction
  • unmapped_segments lists segment IDs that had no mapping rule (useful for auditing coverage)
  • ADT produces Patient+Encounter, ORM/OMG produces Patient+ServiceRequest, ORU produces Patient (+Encounter from PV1) + Observation per OBX + DiagnosticReport per OBR
  • ORU: each OBR and the OBX segments after it form one DiagnosticReport (status OBR-25, code OBR-4, category OBR-24, effective OBR-7, issued OBR-22, identifiers OBR-2/OBR-3 typed PLAC/FILL) whose result lists exactly that group's Observations; OBX before any OBR stay outside any report
  • Observation: OBX-5 of type NM becomes valueQuantity.value as a JSON number (a non-numeric NM value becomes valueString and a warning, never a number); OBX-6 units, with system http://unitsofmeasure.org when coded as UCUM; OBX-8 abnormal flags become interpretation (v3-ObservationInterpretation); OBX-11 status (empty: final, with a warning; outside table 0085: unknown)
  • Coding systems (OBX-3, OBR-4) go through one v2 → FHIR table: LN → http://loinc.org, SCT/SNM → http://snomed.info/sct, I10 → http://hl7.org/fhir/sid/icd-10, I10C → .../icd-10-cm, UCUM → http://unitsofmeasure.org; ids without a known URI (local codes, CIE-10-ES) are kept as they are and listed in warnings
  • HL7 timestamps without a UTC offset are read in default_timezone; when it is empty, or the local time does not exist there (DST gap) or occurs twice (DST overlap), dateTime values keep only the date and instants (issued) are omitted, each with an entry in warnings; a time is never shifted
  • Unknown message types still attempt best-effort PID and OBX conversion

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..