Skip to content
Healthcare data guides

How to convert HL7 to FHIR R4 and back in your browser

Published 3 min read

Many hospital systems still exchange HL7 v2 messages, while newer systems and APIs use FHIR. Developers and analysts often need to translate between the two, or just see what a conversion looks like. This guide shows how to go from HL7 to FHIR with Convertada's HL7 v2 to FHIR R4 Converter, and back with the FHIR R4 to HL7 v2 Converter. Both run in your browser.

Use test data only

Do not paste real patient information. The tools run in your browser and do not store or send your messages, but use synthetic or properly de-identified data unless you are authorised to handle real data and your device and network are secure. Convertada makes no claim of HIPAA, GDPR or other regulatory compliance.

HL7 v2 to FHIR R4

The converter handles these HL7 v2 message types: ADT, ORU, ORM and SIU. The output is FHIR R4.

Step-by-step

  1. Open the HL7 v2 to FHIR R4 Converter.
  2. Paste a message, drop a text file (up to 5 MB) or select Example to load a sample.
  3. Choose the Bundle type:
  • Collection: a plain set of resources, with no MessageHeader.
  • Message: adds a MessageHeader built from MSH, with the source endpoint derived from MSH-3.
  • Transaction: each resource becomes a PUT with a stable id, so re-sending an update, such as an ADT^A08, replaces the earlier data.
  1. Set the Assumed time zone for timestamps without a zone. If you leave it empty, only the date is kept for those timestamps.
  2. Select Convert.
  3. Review the result, then copy or download the FHIR JSON.

Read the conversion report

The most useful part is the report that comes with the output:

  • A conversion summary: the source message, its control ID, the target, the resources created and counts of mapped and unmapped fields.
  • Errors, warnings and notes, with a location, a message and a suggested correction.
  • A list of unmapped fields and unsupported segments or resources, so you know what did not carry over.
  • Mapping information, showing how source fields map to target elements.

The tool also checks the generated FHIR against the FHIR R4 JSON Schema. This is structural validation, not profile validation.

FHIR R4 to HL7 v2

The reverse converter generates HL7 v2.5.1 ADT, ORU, ORM and SIU messages from supported FHIR R4 resources.

  1. Open the FHIR R4 to HL7 v2 Converter.
  2. Paste your FHIR JSON or load the example.
  3. Leave Message type on Detect from resources, or choose one.
  4. Fill in the optional message header values: message control ID (leave it empty to generate one), sending and receiving application and facility.
  5. Check the Processing ID. It defaults to Training (T) so that test data is never mistaken for production.
  6. Select Convert, then check the source FHIR validation, the generated HL7 and its validation.

Segments are shown on separate lines in the page, while the downloaded file separates segments with a carriage return, as HL7 requires.

What to expect and what not

  • Only supported message types and resources are converted. Anything else appears in the unsupported list.
  • Unmapped fields are reported, not silently dropped.
  • It is not a certified interface. Check the output against your own profiles and requirements before you rely on it.
  • Validation is structural. Local profiles, business rules and terminology are not checked.

Common problems and how to fix them

"The message must start with an MSH segment." Remove leading text, and make sure the first segment is MSH.

Timestamps lose their time. Set the Assumed time zone for timestamps that have no zone.

The file is rejected. Files must be text and up to 5 MB.

Frequently asked questions

Are my messages uploaded?

No. They are processed in your browser. Use test data anyway.

Which HL7 versions work?

The tools are tested with versions 2.3.1, 2.4 and 2.5.1, and other valid versions may produce a note.

Can I validate the FHIR it creates?

The tool checks it structurally. For a standalone check, see the FHIR validator guide.

How do I inspect an HL7 message first?

See how to read an HL7 message.

Conclusion

Convert, read the report, and check what was left unmapped. The converters are practical for learning, testing and prototyping, and not a replacement for a validated integration engine.