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.
What you get, and what you do not
This was run on the real engine with a synthetic ADT^A01 message:
| Result | Detail |
|---|---|
| Patient | Identifier (the MRN from PID-3), name, birth date, gender |
| Encounter | Class IMP (inpatient), status in-progress, location from PV1-3, linked to the Patient |
| Not converted | The 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 alwaysin-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
- Permissions. You can open Tiet · Studio → Workflows.
- FHIR server. You have its base URL (for example
https://fhir.example-hospital.org/r4) and a bearer token. - Network. The workflow engine receives HL7 on one server-wide port,
2575by default (set by your administrator withMLLP_PORT). The hospital interface sends to<your-hydra-host>:2575. The listener's ownlisten_portsetting must equal that server port, because it is how the workflow is matched. Itslisten_hostsetting is not used: the bind address is also server-wide. - The sender's names. Ask for the sending application and facility (MSH-3 and MSH-4); you can filter on them.
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
- Open Tiet · Studio → Workflows and choose New Workflow.
- 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.
| Setting | Value | Notes |
|---|---|---|
listen_port | 2575 | Must equal the server's MLLP port |
filter_message_type | ADT | Ignore anything that is not ADT |
filter_event | A01 | Admissions only. Leave empty to accept every event (and see the limits above) |
filter_sending_application | e.g. EPIC | Optional |
filter_sending_facility | e.g. GENHOSP | Optional |
ack_mode | auto | The 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_filter | false | See the table of failures below |
allowed_ips | e.g. 10.0.0.0/24 | Optional: 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.
| Setting | Value |
|---|---|
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.
| Setting | Value |
|---|---|
fhir_url | https://fhir.example-hospital.org/r4 (or {{FHIR_URL}} with a non-secret variable) |
operation | transaction |
auth_token | Paste the token into this field |
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
| From | Port | To | Port |
|---|---|---|---|
| HL7 Listener | raw_message | HL7 to FHIR | hl7_message |
| HL7 to FHIR | result | Pick the Bundle | input |
| Pick the Bundle | result | FHIR CRUD | bundle |
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
- The run. Open Tiet · Studio → Workflows → Monitor. The run for your workflow should show all four nodes succeeded.
- 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 classIMPat locationMED 301 A GENHOSP. The spouse is not there, because NK1 is not converted.
When something goes wrong
| Symptom | Cause | What to do |
|---|---|---|
| The sender cannot connect | Nothing listens on the server port, or a firewall blocks it | Ask your administrator to confirm MLLP_PORT and that the port is open from the hospital network |
| The sender gets AR | No 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_filter | Save 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 happens | Every listener filtered the message out. By default a filtered message is acknowledged AA and ignored | Check 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 node | The FHIR write failed | Open 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 Bundle | Check the Pick the Bundle step and its mappings |
INVALID_MSH_SEGMENT or MISSING_HL7_MESSAGE | The listener node got no message, or the MSH segment is missing or has fewer than 10 fields | Check the MSH segment of the message |
| The sender gets AR for a large message | The message is over the workflow's max_message_size | The 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-fhiralso 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
conditionnode 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.