Skip to main content

Recipe: Receive HL7 ADT messages into FHIR

Goal: a hospital system sends admission messages (HL7 v2 ADT) to Tietai. A workflow receives each one, converts it into a FHIR Patient and Encounter, and writes them to your FHIR server.

You need: about 30 minutes, permission to build workflows, a FHIR R4 server URL and access token, and someone on the hospital side who can send HL7 to a host and port.

A hospital system sends an HL7 message to the workflow engine MLLP server on port 2575, which finds the saved workflows with an hl7-listener node, runs the workflow, and returns an acknowledgement. The workflow converts the message to a transaction Bundle and writes it with fhir-crud.

What you get, and what you do not​

This was run on the real engine with a synthetic ADT^A01 message:

ResultDetail
PatientIdentifier (the MRN from PID-3), name, birth date, gender
EncounterClass IMP (inpatient), status in-progress, location from PV1-3, linked to the Patient
Not convertedThe next of kin (NK1), the visit number, event details (EVN), allergies and diagnoses. The run reports NK1 in unmapped_segments.

Know these limits before you rely on it:

  • Every message creates new resources. Each entry is a POST. There is no match against an existing patient, no update, and the Encounter status is always in-progress.
  • So a discharge (A03) does not close the encounter, an update (A08) creates a second Patient and Encounter, and resending the same message duplicates it.
  • Start with admissions only (filter_event = A01), and add your own matching or update step before you accept other events.

Before you start​

  1. Permissions. You can open Tiet · Studio → Workflows.
  2. FHIR server. You have its base URL (for example https://fhir.example-hospital.org/r4) and a bearer token.
  3. Network. The workflow engine receives HL7 on one server-wide port, 2575 by default (set by your administrator with MLLP_PORT). The hospital interface sends to <your-hydra-host>:2575. The listener's own listen_port setting must equal that server port, because it is how the workflow is matched. Its listen_host setting is not used: the bind address is also server-wide.
  4. The sender's names. Ask for the sending application and facility (MSH-3 and MSH-4); you can filter on them.
Every saved listener workflow receives every message on that port

The server hands each incoming message to every saved workflow that contains an hl7-listener node on that port. The search does not look at whether the workflow is deployed, active, or which organization it belongs to. Do not leave a test workflow saved while live traffic is flowing, and ask your administrator to confirm that no other saved workflow listens on your port.

Build the workflow​

1. Create it​

  1. Open Tiet · Studio → Workflows and choose New Workflow.
  2. In the Palette tab, search for each node below and drag it onto the canvas. Select a node to edit it in the Inspector (Display name under Identity, the settings under Node Settings; the listener's settings are split over the tabs Connection, Filtering, Security, Ack and Advanced).

2. Configure the four nodes​

hl7-listener (HL7 Listener) receives the message and sends the acknowledgement.

SettingValueNotes
listen_port2575Must equal the server's MLLP port
filter_message_typeADTIgnore anything that is not ADT
filter_eventA01Admissions only. Leave empty to accept every event (and see the limits above)
filter_sending_applicatione.g. EPICOptional
filter_sending_facilitye.g. GENHOSPOptional
ack_modeautoThe listener replies after the run: AA (accepted), AE (the run failed) or AR (rejected before processing). manual lets the run set the code; none sends no acknowledgement
nack_on_filterfalseSee the table of failures below
allowed_ipse.g. 10.0.0.0/24Optional: accept connections only from the hospital network

hl7-to-fhir (HL7 to FHIR) needs no settings. Set default_timezone (for example Europe/Madrid) if the message timestamps carry no time zone. It detects the type from MSH-9 and returns an object result that contains the Bundle in fhir_bundle.

transform, named Pick the Bundle, takes the Bundle out of that object so the write node receives a Bundle and not its wrapper.

SettingValue
Transformation Type (transformation_type)extract
Mappings (mappings)Choose Add field three times; in each row type the Target and the Source (dot path ok): resourceType from input.fhir_bundle.resourceType, type from input.fhir_bundle.type, entry from input.fhir_bundle.entry

fhir-crud (FHIR CRUD) writes the Bundle.

SettingValue
fhir_urlhttps://fhir.example-hospital.org/r4 (or {{FHIR_URL}} with a non-secret variable)
operationtransaction
auth_tokenPaste the token into this field
Where the token goes

auth_token is a secret field: paste the token into it. Do not store it as a variable marked secret and write {{FHIR_TOKEN}}: a secret variable is not substituted, so the server would receive the literal text Bearer {{FHIR_TOKEN}}. A non-secret variable is fine for the URL.

3. Connect the ports​

FromPortToPort
HL7 Listenerraw_messageHL7 to FHIRhl7_message
HL7 to FHIRresultPick the Bundleinput
Pick the BundleresultFHIR CRUDbundle

raw_message is text and hl7_message expects text, so they connect. If you wire result straight into bundle, the write node receives the wrapper object and fails with transaction input must be a Bundle, got resourceType=<nil>. That is why the extract step is there.

4. Validate and save​

Choose Validate in the toolbar, then Save (it asks for a version; accept the suggestion). The workflow starts receiving as soon as it is saved. Deploy (the purple menu at the right of the toolbar, which deploys the saved version to another environment) is not needed for it to receive messages, and it does not limit which messages it receives.

Test it with a synthetic message​

Use synthetic data only. This message is a made-up admission:

MSH|^~\&|EPIC|GENHOSP|TIETAI|HIP|20260915083000||ADT^A01^ADT_A01|SMP-A01-0001|P|2.5
EVN|A01|20260915083000|||USR100^Nurse^Maria
PID|1||MRN100001^^^GENHOSP^MR||Rivera^Elena^M||19750312|F|||742 Evergreen Terrace^^Springfield^IL^62704^USA||(217)555-0142||en|M
NK1|1|Rivera^Carlos|SPO^Spouse^HL70063||(217)555-0143
PV1|1|I|MED^301^A^GENHOSP|E|||2001^Smith^Anna^^^Dr|||MED||||7|||2001^Smith^Anna^^^Dr||V2026091501^^^GENHOSP^VN

HL7 separates segments with a carriage return, not a line feed. The simulation tool in the repository sends it correctly and waits for the acknowledgement:

# from the tietai-simulation-service folder
sim-cli hl7 send -H <your-hydra-host> -p 2575 --file samples/hl7v2/adt_a01_admit.hl7 -v

An acknowledgement of AA means the message was accepted for processing.

Check the result​

  1. The run. Open Tiet · Studio → Workflows → Monitor. The run for your workflow should show all four nodes succeeded.
  2. The data. Open FHIR Server → Patients and search for identifier=MRN100001 (a search containing = is sent to the server as a FHIR search parameter). You should find the Patient Rivera, Elena, female, born 1975-03-12, with one Encounter of class IMP at location MED 301 A GENHOSP. The spouse is not there, because NK1 is not converted.

When something goes wrong​

SymptomCauseWhat to do
The sender cannot connectNothing listens on the server port, or a firewall blocks itAsk your administrator to confirm MLLP_PORT and that the port is open from the hospital network
The sender gets ARNo saved workflow has an hl7-listener on that port (the server's default reply when none listens); or the header is unreadable (MSH-9, MSH-10 or MSH-12 missing) or the version is not HL7 v2.x; or this workflow's allowed_ips or max_message_size refused the message; or every listener filtered it out and one sets nack_on_filterSave the workflow and check listen_port equals the server port, then check the MSH segment and the sender's IP address
The sender gets AA but nothing happensEvery listener filtered the message out. By default a filtered message is acknowledged AA and ignoredCheck filter_message_type, filter_event, and the sender and facility names. Set nack_on_filter to true to answer AR instead, so the sender sees the problem
The run fails at the last nodeThe FHIR write failedOpen the run in Monitor. fhir_url is required means the URL is empty; a rejected request usually means the token or the URL is wrong
transaction input must be a Bundle, got resourceType=<nil>The write node received the wrapper object, not the BundleCheck the Pick the Bundle step and its mappings
INVALID_MSH_SEGMENT or MISSING_HL7_MESSAGEThe listener node got no message, or the MSH segment is missing or has fewer than 10 fieldsCheck the MSH segment of the message
The sender gets AR for a large messageThe message is over the workflow's max_message_sizeThe default maximum is 1048576 bytes (1 MiB); 0 removes the per-workflow limit. The server has its own cap too

Adapt it​

  • Results (ORU) or orders (ORM): hl7-to-fhir also maps ORU to Patient plus Observation and DiagnosticReport, and ORM to Patient plus ServiceRequest. Change the filter and keep the rest.
  • React to what arrives: add a condition node after the conversion (see Build any workflow), for example to route admissions to a particular ward.
  • Several hospitals or sites: place a listener at each site with Run on mesh.
  • As a Connect pipe instead: Create a Connect pipe receives HL7 with a pipe. Read its notes on FHIR conversion before you choose that route.

Something unclear? Send documentation feedback by email.