web stats
Skip to end of metadata
Go to start of metadata

Before continuing, read the FHIR Connector overview and user guide if you haven't already:

Along with the Example Channel, we're also providing some sample code templates, transformers, and channels to help you kickstart any HL7 v2.x to FHIR conversions you need to do.


The code made available here is not guaranteed to work 100% in all cases! As with any HL7 interface, some extra tweaks are usually needed to ensure that it fits your specific workflow.


This page is separated into the following sections:


These examples are also hosted on our public GitHub repository! Contribute and collaborate with us to make them even better!





If you've never worked with FHIR before, converting HL7 v2.x messages to FHIR resources may seem a daunting task. However the FHIR documentation actually provides a lot of useful information that can cover most of the broad strokes.

For the examples in this section, we're going to be looking at taking an HL7 v2.x ADT, and creating a FHIR Patient resource that represents the demographic information present in the message.

From the Patient documentation page, click on Mappings, and search for "HL7 v2". Or go directly to this link: http://hl7.org/fhir/STU3/patient-mappings.html#v2

You'll see that most of the FHIR resource properties have corresponding HL7 v2.x segment and field mappings. For example, the Patient.identifier property is mapped to the PID-3 field. But how exactly does each individual PID-3 component map into the identifier property?

Return to the Content tab, and look at the structure of the resource. You'll see that the "identifier" property is of type Identifier.

Click on Identifier to navigate to the documentation page for that data type: http://hl7.org/fhir/STU3/datatypes.html#Identifier. Then click on Mappings to view the HL7 v2.x mappings for that data type: http://hl7.org/fhir/STU3/datatypes-mappings.html#Identifier

This should give you enough information to be able to map pieces of the HL7 message into the corresponding FHIR resource properties. To see how, read on...

Convert HL7 to FHIR Patient - Example 1

Download the "Convert HL7 to FHIR Patient - Example 1.xml" file from the Downloads section, and import the channel into your Mirth Connect server.

This channel includes the "HL7 v2.x to FHIR Helper Functions" code template library. If you already have that library imported, you may see a dialog asking whether or not you want to overwrite the library. To overwrite the library and all of its code templates, click the "Overwrite: All" link in the top-right, and then click Import.

If you don't want to overwrite any libraries or code templates, click Cancel, then Yes when prompted to continue without importing. Then make sure the library is enabled for your newly imported channel:


Once you've imported the channel, go to the Source tab, and click Edit Transformer to view the source transformer. You'll see quite a few Iterator steps with FHIR Resource Builders. These are dynamically creating the identifiers, names, telecoms, etc. that will go into the final Patient resource. For example, step 0-0 "Create Identifier" handles the creation of a single Identifier data type:

The parent Iterator step will loop through each PID-3 field, create a new Identifier for the field, and add it to an array. We use the name "identifiers" and store it as a local variable. That means that the variable "identifiers" will only be accessible in this transformer. This variable is used later on in step 9, "Create Patient":

In this example we're also storing the Patient object as a local variable, "patient". The final step calls a couple of helper methods in the code template library to consolidate and cleanup any properties in the Patient that were empty or non-valued.

Check out the "HL7 v2.x to FHIR Helper Functions" library if you're wondering what exactly those code templates are doing.


Deploy the channel, and send a sample ADT message through it:

If you look at the Source Encoded data or the Destination Raw data, you'll see that it has been converted into a FHIR JSON resource!

Convert HL7 to FHIR Patient - Example 2

The first example channel used the FHIR Resource Builder transformer step to create a FHIR Patient resource from an HL7 ADT. This next channel will do the same thing, but using code templates instead. The advantage to using code templates is that you can re-use the same code/builder across multiple transformers, connectors, and channels.

Download the "Convert HL7 to FHIR Patient - Example 2.xml" file from the Downloads section, and import the channel into your Mirth Connect server.

This channel includes both the "HL7 v2.x to FHIR Helper Functions" and "HL7 v2.x to FHIR Creation Functions" code template libraries. Follow the instructions in the previous section to make sure you have both of these libraries linked to your newly imported channel.


Once you've imported the channel, go to the Source tab, and click Edit Transformer to view the source transformer. You'll see that now there's only a single, simple Message Builder step:

To actually see what's happening, go back to the Channels view, then click "Edit Code Templates" to enter the Code Templates view. In the "Creation Functions" library, you'll see many of the same FHIR Resource Builders that we saw from the first channel.

For example, the "Create FHIR Patient Identifier" code template creates a new function: createPatientIdentifier(pid3). The "pid3" argument gets passed in, and then used in the builder properties:

To handle iterating through multiple segments/fields, separate code templates are created. For example, the "Create FHIR Patient Identifiers" code template takes in a PID segment, iterates through all PID-3 fields, and returns an array of FHIR Identifier objects:

The "Create FHIR Patient" code template brings it all together to construct the Patient resource. Then finally, the "Create and Consolidate FHIR Patient" code template calls the createFhirPatient method, and then also does the cleanup and consolidation that we saw before.

Deploy the channel and send a sample ADT message to it (look at the previous section for a sample ADT). As before, you'll see that the Source Raw data is the HL7 ADT, and the Source Encoded / Destination Raw data is the JSON representation of the FHIR Patient resource!

Next Steps

As with the FHIR Listener Example Channel, these sample code templates and channels are only meant to be a starting point. You will likely need to tweak them in order to fit your specific use-cases. The FHIR documentation pages are a great starting place to see how the HL7 to FHIR mapping should take place. Perhaps try building on these examples to also create an associated Encounter resource from the ADT!

  • No labels

1 Comment

  1. when I try to send a resource to the FHIRSender destination I am not able to set the content-type due to that I am getting an error when posting the patient resource to the fhir listener channel. I am getting the below error


    FHIR Sender error

          "div":"<div xmlns=\"http://www.w3.org/1999/xhtml\"><hr/><ul><li><span style=\"font-weight: bold;\">ERROR</span><ul><li> Type: <span>TRANSIENT</span></li><li> Details: <pre>Error creating resource.</pre>\n\t\t\t\t</li>\n\t\t\t\t\n\t\t\t\t\n\t\t\t</ul>\n\t\t</li>\n\t</ul>\n</div>"
                "text":"Error creating resource."