HL7 to FHIR | Medplum

On this page

HL7 interfaces are common in healthcare, and widely supported by legacy EHRs, RIS/PACS systems, lab machines and more. Medplum provides a HL7 Interfacing engine that supports consumption and production of HL7 feeds, and the Medplum Agent supports connecting to systems on-premises.

This guide will show you [​](/content/docs/bots/hl7-into-fhir#this-guide "Direct link to This guide will show you"/index.html)

The Workflow [​](/content/docs/bots/hl7-into-fhir#the-workflow "Direct link to The Workflow"/index.html)

When this implementation is complete we will:

The Implementation [​](/content/docs/bots/hl7-into-fhir#the-implementation "Direct link to The Implementation"/index.html)

Account and Policy Setup [​](/content/docs/bots/hl7-into-fhir#account-and-policy-setup "Direct link to Account and Policy Setup"/index.html)

Bot Setup [​](/content/docs/bots/hl7-into-fhir#bot-setup "Direct link to Bot Setup"/index.html)

// SPDX-FileCopyrightText: Copyright Orangebot, Inc. and Medplum contributors

// SPDX-License-Identifier: Apache-2.0

import type { BotEvent, Hl7Message, MedplumClient } from '@medplum/core';

import type { Patient } from '@medplum/fhirtypes';

export async function handler(medplum: MedplumClient, event: BotEvent): Promise<Hl7Message> {

const input = event.input as Hl7Message;

// Log Message Type

const messageType = input.getSegment('MSH')?.getField(9);

console.log(messageType);

// Get patient name

const givenName = input.getSegment('EVN')?.getField(6).getComponent(2) as string;

const familyName = input.getSegment('EVN')?.getField(6).getComponent(3) as string;

// Get patient ID

const mrnNumber = input.getSegment('PID')?.getField(4).getComponent(5);

let patient = await medplum.searchOne('Patient', 'identifier=' + mrnNumber);

if (patient) {

console.log('Patient already in the system');

} else {

patient = await medplum.createResource<Patient>({

resourceType: 'Patient',

name: [
        {
          given: [givenName],
          family: familyName,
        },
      ],

identifier: [
        {
          system: 'www.myhospitalsystem.org/IDs',
          value: mrnNumber,
        },
      ],
    });

console.log('Created patient', patient.id);
  }

// Based on the messageType, you may consider making additional FHIR objects here

// Return Ack
  return input.buildAck();
}

Functionally, the code above will create a new patient with the mrnNumber provided, assuming that patient isn't already in this system.

Testing your Bot [​](/content/docs/bots/hl7-into-fhir#testing-your-bot "Direct link to Testing your Bot"/index.html)

You'll need your bot id (see bot list and click) to execute the bot. Once you have found it, you can attempt to execute your Bot using an HTTP message by sending the following via curl. Note the content type.

curl -X POST 'https://api.medplum.com/fhir/R4/Bot/<bot-id>/$execute' \
--header 'Content-Type: x-application/hl7-v2+er7' \
--header 'Authorization: Bearer <access_token>' \
--data-raw 'MSH|^~\\&|Primary||CL|PDMT|20200312081842|168866|ADT^A28|203598|T|2.3|||||||||||\nEVN|A28|20200312081842||REG_UPDATE|168866^GLOVER^JASMIN^^^^^^PHC^^^^^10010||\nPID|1||E3866011^^^EPIC^MRN~900093259^^^EPI^MR||TESTING^UGA||20000312|M|||^^^^^USA^P||||||||123-54-8888|||||N||||||N||\nPD1|||PHYSICIANS ATLANTIC STATION^^10010|||||||||||||||\nPV1|1|N||||||||||||||||||||||||||||||||||||||||||||||||||\nPV2||||||||||||||||||||||N|||||||||||||||||||||||||||'

If all goes well, you should see the following HL7 acknowledgement message in the console.

MSH|^~\\&|CL|PDMT|Primary||2022-05-10T16:19:50.244Z||ACK|1652199590244|P|2.5.1\rMSA|AA|203598|OK

Alternatively, you can submit the HL7 message type to the bot as a file using the following command.

curl -x POST 'https://api.medplum.com/fhir/R4/Bot/<bot-id>/$execute' \
  --header 'Content-Type: x-application/hl7-v2+er7' \
  --header 'Authorization: Bearer <access_token>' \
  --data-binary "@/path/to/filename"

Creating a subscription [​](/content/docs/bots/hl7-into-fhir#creating-a-subscription "Direct link to Creating a subscription"/index.html)

If you want to receive a notification whenever a Patient (or other FHIR resource) is created, you can do so by creating a Subscription.

Subscriptions have a concept of Criteria which indicates when they should be triggered. Link them to the FHIR resource of choice.

Complex Logic in Bots [​](/content/docs/bots/hl7-into-fhir#complex-logic-in-bots "Direct link to Complex Logic in Bots"/index.html)

Creating a patient from a single type of HL7 message is straightforward and doesn't require much code.

In practice, this is unrealistic, and the code will soon require a more complex application with testing and strongly typed objects. To support that we have a Bot toolkit for development and deployment that you can find here: CLI Tool.