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](/content/docs/integration/hl7-interfacing/index.html) that supports consumption and production of HL7 feeds, and the [Medplum Agent](/content/docs/agent/index.html) 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)

- How to integrate Medplum with an HL7 feed bi-directionally, receiving messages and sending back confirmation messages.
- How to convert those HL7 messages into FHIR objects

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

When this implementation is complete we will:

- Receive an HL7 message over HTTPS from another EHR that produces HL7 feeds
- Create FHIR objects that capture the parts of the feed we care about.
- Respond to the EHR with an HL7 acknowledgment that the message was received
- (Optional) Send a notification to another application, indicating that new FHIR resources are available.

## 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)

- Make sure you have an account on Medplum, if not, [register](https://app.medplum.com/register).
- Create a [ClientApplication](https://app.medplum.com/admin/project) on Medplum called "ADT Bot Client Application".
- (Optional) Create a very restrictive [AccessPolicy](https://app.medplum.com/AccessPolicy) called "ADT Bot Policy", make it so that the policy only allows readwrite on the Patient object.
- (Optional) In the [ProjectAdmin dashboard](https://app.medplum.com/admin/project) apply the "ADT Bot Policy" policy to the `ClientApplication` by clicking `Access`.

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

- Linking the ADT feed to Medplum is done through [Medplum Bots](https://app.medplum.com/Bot).

- At a high level, each Bot exposes an endpoint and HL7 messages are posted over HTTPS to that endpoint.

- The HL7 message is parsed and then converted to a corresponding FHIR object.

- (Optional) If needed, you can link a [Subscription](https://app.medplum.com/Subscription) to the FHIR objects that the Bot creates to notify downstream applications that new data is available.

- Make the bot that will listen for HL7 messages
  - First, [create a bot](https://app.medplum.com/admin/project) called ADT Handler Bot and save it
  - Paste the code below into the Bot you created and save. You can also find this bot and a corresponding test in the [Sample Bots Github Repository](https://github.com/medplum/medplum-demo-bots/).

```ts
// 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](https://app.medplum.com/Bot) 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.

```bash
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.

```text
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.

```bash
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](/content/docs/bots/bot-basics#executing-automatically-using-a-subscription/index.html).

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](https://github.com/medplum/medplum-demo-bots).