HL7 v2.x Parser
Vorian Connect parses HL7 v2.x messages from clinical analyzers with full support for multi-occurrence segments, vendor-specific dialect remapping, and automatic LOINC code enrichment. Every message gets a standards-compliant ACK or NACK — the instrument never waits on cloud delivery.
How It Works
- Raw HL7 messages arrive at the edge agent over MLLP (Minimal Lower Layer Protocol) — the standard framing used by virtually every clinical analyzer
- The parser auto-detects encoding characters from the MSH segment, supporting non-standard field, component, and sub-component separators that some vendors use
- Each message is decomposed into typed segments (MSH, PID, OBR, OBX, etc.) with field, component, and sub-component accessors — no regex scraping required for downstream processing
- Multi-occurrence segments (such as repeated OBX segments for panel results) are serialized as JSON arrays, preserving the full structure of the original message
- A vendor dialect layer remaps non-standard field positions to canonical names — the same result value that appears in OBX-5 for one instrument and OBX-6 for another is normalized to a consistent path
- Built-in dialects for Beckman Coulter AU and Sysmex XN analyzers handle manufacturer-specific segment layouts and Z-segment extensions
- After parsing, the normalization engine enriches each OBX segment with LOINC codes, display names, canonical units, and abnormal flag interpretation from a built-in map of 35 common clinical analytes
What's Included
- Full HL7 v2.x parser: Segment, field, component, and sub-component extraction with typed accessors (
Message.Get(),Segment.Field(),Segment.Component()) - Encoding character auto-detection: Reads the MSH-1 and MSH-2 fields to discover the actual delimiters used, handling vendors that deviate from the standard pipe/caret/tilde/backslash defaults
- Escape sequence decoding: HL7 escape sequences (e.g.,
\F\for field separator,\S\for component separator) are decoded during parsing - Dialect registry: Vendor-specific field remapping and Z-segment definitions — add a new dialect without changing parser code
- LOINC normalization: 35 common analytes mapped to LOINC codes with canonical units and display names; results are enriched with a
_loincsub-object on each OBX - ACK/NACK logic: Parse failures return
MSA|AE(Application Error); successful DB commits returnMSA|AA(Application Accept). The edge agent ACKs immediately per the store-and-forward contract - Field repetition support: HL7 fields with repetition separator (~) are split into individual repetitions with component-level access on each
Where It Fits
The HL7 parser runs inside the Vorian edge agent, processing messages immediately after they arrive over MLLP. The parser feeds into the auto-verification engine (rules, ranges, delta checking) and the downstream delivery subsystem (webhook, MLLP forwarding, FHIR R4). It shares the same agent infrastructure as the ASTM E1381 parser — labs running a mix of HL7 and ASTM instruments use one agent, one install, one dashboard.
Parsed messages are available in the Trace Inspector as a double-pane view: raw HL7 text on one side, structured JSON on the other. Every field, segment, and LOINC enrichment is visible and searchable.
Technical Details (for evaluators)
The parser is written in Go and handles the full HL7 v2.x message structure — MSH through any terminal segment — with support for non-standard line endings (CR, LF, CRLF). Multi-occurrence segments (OBX, NTE, etc.) are preserved as ordered arrays in the parsed output. The parser rejects messages that do not begin with an MSH segment as required by the HL7 standard.
The dialect system maps instrument-specific field positions to a canonical namespace. For example, a Beckman Coulter AU analyzer might place the test code in a different OBX field than a Sysmex XN — the dialect layer normalizes both to OBX.<code>.value before the message reaches the rules engine. Adding support for a new instrument model requires only a dialect definition; no parser changes are needed.
The LOINC map covers 35 common chemistry, hematology, and immunoassay analytes. Each mapping includes the LOINC code, preferred display name, canonical UCUM unit, and flag label interpretation for abnormal result flags.