Debugging HL7 by workflow: what to check first
When an HL7 interface fails, it is tempting to start by staring at the segment reference. That helps, but the faster first question is: what workflow was this message trying to perform? Admit a patient, place an order, report a result, post a charge, file a document, update a schedule, or synchronize a master file?
Once you know the workflow, the first fields to check become obvious. For ADT, check MSH-9, PID-3, PV1-2, PV1-3, PV1-19, and event/cancel/merge logic. For orders, check ORC-1, ORC-2, ORC-3, OBR-4, and status. For results, check OBR/OBX grouping and OBX-11.
This is synthetic sample data for learning and testing. Open it in HL7 Soup Web before mapping it so the segment groups, repeated fields, and coded values are visible.
Use A Workflow Debugging Order
Start with the envelope: MSH sender, receiver, version, message type, control ID, processing ID, and timestamp. Then check identity: patient ID, assigning authority, visit/account/order identifiers. Then check the event or status: ADT trigger, ORC control, result status, document status, schedule action, or FT1 transaction type.
Only after that should you dive into individual field formatting. A datatype problem matters, but it may not be the root cause if the message is simply going to the wrong receiver or asking for the wrong workflow action.
- Check whether the receiver rejected syntax, profile conformance, business state, or duplicate detection.
- Compare raw inbound, transformed outbound, and receiver ACK.
- Never debug from screenshots when the raw HL7 is available.
ACKs Tell A Story
An ACK is not just success/failure. MSA links the response to the original message control ID, and ERR may point to the offending segment, field, component, and error code. Preserve the ACK in support logs.
Check The Loop Binding
If a transformation only outputs the first OBX, first FT1, or first OBR group, check whether the loop is actually bound to the repeated segment or group. A label or literal text that says "OBX" is not the same as a binding to the repeating OBX collection. Put the append, insert, or write action inside the loop, and keep shared patient/order context outside it.
This is one of the quickest things to confirm in Integration Soup: the repeated value should drive the For Each, and the output action should run once per repeat. The repeating OBX tutorial shows the pattern even when the real destination is SQL, JSON, or a billing message rather than CSV.
A Practical Integration Soup Workflow
Use HL7 Soup Web for quick visual inspection and sharing a de-identified sample with another implementer. Use Integration Soup for production evidence: inbound raw message, transformed outbound, destination, ACK, retry history, logs, and variables.
The Integration Host getting started tutorial, file-processing tutorial, and transformers tutorial are the practical base for building workflows that can be debugged later.
Workflow Checklists
For ADT, check patient, visit, event, cancel, merge. For orders, check order control, placer/filler IDs, service code, timing, provider. For results, check OBR/OBX grouping, status, value type, abnormal flags. For documents, check TXA/document ID/status/payload. For billing, check FT1 transaction ID/type/amount and duplicate logic.