HL7 v2.4 · MLLP · File I/O
Standard HL7 v2.4 LIS interface
This document defines the wire protocol between your Laboratory Information System (LIS) and TransLABtor middleware.
Implement the message structures below to send orders to TransLABtor and receive results and status updates.
TransLABtor driver type: hl7_standard_lis.
- Document version
- 1.0.0
- Last updated
- 8 September 2026
1. Integration topology
TransLABtor sits between the LIS and clinical analyzers. Your LIS integration connects to the TransLABtor LIS channel — not directly to individual instruments.
- LIS → TransLABtor: laboratory orders (
ORM^O01), optional inbound results (ORU^R01), storage (OUL^R22) - TransLABtor → LIS: validated results (
ORU^R01), specimen status (SSU^U03)
Connection modes: TCP Server, TCP Client, or File I/O (drop folders). Port assignment is configured per site during deployment. Avoid ports reserved by the TransLABtor platform (e.g. 3051, 8051); ports above 10000 are recommended for custom TCP listeners.
2. Transport — MLLP (TCP)
HL7 payloads over TCP use Minimal Lower Layer Protocol (MLLP) framing:
VT (0x0B) + HL7 message + FS (0x1C) + CR (0x0D)
- Segment terminator inside the HL7 body:
CR(0x0D) — one segment per line - Field separator:
|(pipe, ASCII 124) - Encoding characters (MSH-2): typically
^~\\& - HL7 version in MSH-12:
2.4
TransLABtor accumulates partial TCP reads until a complete MLLP frame (VT … FS CR) is received. A frame missing the FS end block is rejected.
3. Transport — File I/O
When File I/O mode is enabled on the LIS connection:
- Inbound (LIS → TransLABtor): write HL7 files to the configured
incoming_directory. Processed files are moved toincoming_directory/Archive/. - Outbound (TransLABtor → LIS): ORU and status files are written to
outgoing_directorywith configurable extensions (default.hl7). - File content is raw HL7 (segments separated by CR); MLLP wrappers are not required for files.
4. Message types
| Direction | MSH-9 | Purpose |
|---|---|---|
| LIS → TL | ORM^O01 | New or updated laboratory order (one or more tests per message) |
| LIS → TL | ORU^R01 | Inbound result (optional passthrough; production path is instrument → TL → LIS) |
| LIS → TL | OUL^R22 | Storage / specimen management detail |
| LIS → TL | SSU^U03 | Status update (EQU + SAC segments) |
| TL → LIS | ORU^R01 | Outbound validated test results |
| TL → LIS | SSU^U03 | Outbound specimen status |
| TL → LIS | ACK | Application acknowledgement for inbound MLLP messages |
Legacy support: OML^O33 status messages are accepted for backward compatibility.
5. Acknowledgements (MLLP)
For each inbound MLLP message, TransLABtor returns an HL7 ACK wrapped in MLLP:
- Success:
MSA-1 = CA(Commit Accept) - Failure:
MSA-1 = AE(Application Error) - MSA-2: echoes inbound
MSH-10(Message Control ID) when present - MSA-3: error text when
AE
Your LIS should treat AE as a hard failure — the order or result was not accepted. Do not assume silent suppression.
6. Inbound validation rules
| Rule | Behavior if violated |
|---|---|
MSH-11 Processing ID must match site configuration (default P) | Reject with AE |
PID-8 Sex, when present, must be M or F | Reject with AE |
specimen_id required on orders and results | Reject with AE |
Patient ID consistency: if specimen already exists with a stored patient ID, inbound patient_id must match | Reject with AE (patient safety guard) |
| Microbiology: when isolate-number fields are present, total OBR count must be even (panel + isolate pairs) | Reject with AE |
7. Laboratory order — ORM^O01 (LIS → TransLABtor)
7.1 Segment hierarchy
MSH PID (optional; required if demographics must be stored) [NTE] patient comments [PV1] ORC OBR (repeat per test line) [OBX] previous-result hints only (OBX.3 matches OBR.4) [NTE] specimen / test comments
7.2 Key fields — order ingest
| Field | Usage |
|---|---|
MSH-9 | ORM^O01 |
MSH-11 | P (production) or D (debug) — must match site config |
PID-3 | Patient identifier (required if storing patient demographics) |
PID-5 | Patient name (Last^First^Middle) |
PID-7 | Date of birth YYYYMMDD |
PID-8 | Sex: M or F when sent |
ORC-1 | NW new order; XE add/delete; CA cancel |
OBR-2 / OBR-3 | Specimen ID (placer / filler) — at least one required |
OBR-4 | Test code and name (code^name) |
OBR-15 | Specimen fluid / type (component 1 = fluid; component 4 = site) |
OBR-18 (default) | Routing instrument code — maps to TransLABtor instruments.instrument_code |
OBR-27.6 or ORC-7.6 | Priority; STAT in ORC-7 sets STAT priority |
OBR-15.7 | Q = QC specimen; blank = patient |
Instrument routing field index is configurable per site (lis_instrument_id_obr_field, default 18).
Ensure your LIS sends a stable instrument code that matches the TransLABtor instrument registry.
7.3 Microbiology orders
Micro orders use paired OBR segments: organism/panel OBR followed by isolate OBR.
Isolate numbers appear in OBR fields with prefix ISO (configurable).
An odd number of OBR segments in a micro order is invalid and rejected.
8. Laboratory result — ORU^R01 (TransLABtor → LIS)
8.1 Segment hierarchy
MSH PID [NTE] [PV1] ORC (RE) OBR [NTE] OBX (repeat per result) [NTE]
8.2 Key fields — result outbound
| Field | Usage |
|---|---|
MSH-3..6 | Sending / receiving application and facility (configured per site) |
MSH-9 | ORU^R01 |
OBR-2 | Specimen ID |
OBR-4 | Test code / name |
OBX-2 | Value type (e.g. NM, TX, ST) |
OBX-3 | Observation identifier — LIS test code (from mapping / ordered_lis_test_code) |
OBX-5 | Result value |
OBX-6 | Units |
OBX-8 | Abnormal flags |
OBX-11 | Result status (e.g. F final) |
Outbound ORU composition (include PID, PV1, NTE segments) is configurable per deployment. By default, only validated results are sent to the LIS.
9. Status and storage
Status — SSU^U03 (TransLABtor → LIS)
MSH EQU SAC
SAC-3 / SAC-4 carry specimen identifiers for status updates.
Storage — OUL^R22 (LIS → TransLABtor)
Inbound storage messages are parsed and routed to specimen management. Can be blocked per site if not used.
10. Test and instrument mapping
TransLABtor maps LIS test codes to instrument test codes per target analyzer using driver_test_mappings.
Mapping is scoped by instrument connection, not the LIS connection.
- If a mapping exists: LIS code → instrument wire code before download to analyzer
- If mapping is missing and auto-map is enabled: 1:1 mapping row is created
- If mapping is missing and auto-map is disabled: test line is dropped
- If routing instrument code does not match any registered instrument: test line is skipped
Provide a code crosswalk during scoping or use the TransLABtor mapping UI after go-live.
11. Examples — orders (illustrative)
11.1 One specimen, multiple tests, same instrument
Single ORC, one PID, and one OBR per test line. All lines share specimen ID SM2026001
and route to the same instrument via OBR-18.
MSH|^~\&|LIS|HOSP|TransLABtor|LAB|20260202120000||ORM^O01|MSG00001|P|2.4 PID|1||PAT001||Doe^John||19800101|M ORC|NW|SM2026001||||^^^^^R OBR|1|SM2026001||GLU^Glucose|R|20260202100000|||||SER|||||||HEM001|||||||||||||| OBR|2|SM2026001||BUN^Urea|R|20260202100000|||||SER|||||||HEM001|||||||||||||| OBR|3|SM2026001||CREA^Creatinine|R|20260202100000|||||SER|||||||HEM001||||||||||||||
11.2 One specimen, multiple tests, split by instrument
When tests route to different analyzers, change OBR-18 per line. TransLABtor splits routing per target instrument code.
MSH|^~\&|LIS|HOSP|TransLABtor|LAB|20260202120500||ORM^O01|MSG00002|P|2.4 PID|1||PAT001||Doe^John||19800101|M ORC|NW|SM2026001||||^^^^^R OBR|1|SM2026001||GLU^Glucose|R|20260202100000|||||SER|||||||HEM001|||||||||||||| OBR|2|SM2026001||HGB^Haemoglobin|R|20260202100000|||||SER|||||||HEM001|||||||||||||| OBR|3|SM2026001||PT^Prothrombin Time|R|20260202100000|||||PLASMA|||||||COAG001||||||||||||||
12. Example — result with multiple tests (TransLABtor → LIS)
One ORU^R01 may carry multiple completed tests for the same specimen. Each test uses an OBR followed by one or more OBX segments.
MSH|^~\&|TransLABtor|LAB|LIS|HOSP|20260202143000||ORU^R01|RES00001|P|2.4 PID|1||PAT001||Doe^John||19800101|M ORC|RE|SM2026001 OBR|1|SM2026001||GLU^Glucose|R OBX|1|NM|GLU^Glucose||5.4|mmol/L|3.9-6.1|N|||F OBR|2|SM2026001||BUN^Urea|R OBX|1|NM|BUN^Urea||6.2|mmol/L|2.5-7.1|N|||F OBR|3|SM2026001||CREA^Creatinine|R OBX|1|NM|CREA^Creatinine||88|umol/L|59-104|N|||F
13. Example — ACK success
MSH|^~\&|TransLABtor|LAB|LIS|HOSP|20260202120001||ACK|ACK00001|P|2.4 MSA|CA|MSG00001
14. Deployment parameters (negotiated per site)
| Parameter | Default | Notes |
|---|---|---|
| HL7 version | 2.4 | 2.2 supported |
| Expected processing ID | P | Set to empty to disable check |
| Instrument ID OBR field | 18 | 0-based field index |
| File I/O directories | site-specific | Incoming / outgoing paths |
| MSH sending / receiving IDs | TransLABtor / LIS | Match your LIS expectations |