Parsing HL7 v2 Messages for OpenMed

HL7 v2.x is the workhorse of hospital interfacing, ADT (admit/discharge/ transfer), ORU (observation results), MDM (document management), and ORM (orders) messages flow continuously between EHR, lab, radiology, and ancillary systems. The clinical narrative you want for NLP is buried in OBX-5 (observation value) and NTE-3 (notes/comments) fields, wrapped in a pipe-and-caret encoding. This skill decodes that envelope and hands the free text to OpenMed.

When to use

• You receive HL7 v2 messages from an interface engine (Mirth/NextGen Connect, Rhapsody, Cloverleaf) and want to mine embedded note/result text.
• A lab feed (ORU^R01) carries impression/comment narrative in OBX/NTE.
• An MDM^T02 transcription message carries a full report in OBX-5.
• You need a de-identified, structured feed into openmed.analyze_text.

HL7 v2 structure in one minute

A message is segments separated by \r (carriage return). Each segment is 3-letter-named, then fields split by |, components by ^, repetitions by ~, sub-components by &, with \ as escape. The encoding characters are declared in MSH-1 (the field separator) and MSH-2 (^~\&). Field positions are one-based, and MSH is special: MSH-1 is the separator, so MSH-2 is the first real field.

MSH|^~\&|LAB|HOSP|EHR|HOSP|20240302101500||ORU^R01|MSG0001|P|2.5
PID|1||MRN12345^^^HOSP^MR||DOE^JANE^Q||19700115|F|||1 FAKE ST^^SPRINGFIELD^IL^62704
OBR|1||ORD9|CBC^Complete Blood Count
OBX|1|TX|IMPRESSION||Mild leukocytosis; clinically correlate.||||||F
NTE|1||Patient reports fatigue x1 week. Dr. Smith notified.

Quick start

Parse the envelope and pull narrative from OBX-5 / NTE-3, then hand off:

import openmed
from openmed.interop.hl7v2 import parse_hl7v2

raw = open("results.hl7", encoding="utf-8").read()
msg = parse_hl7v2(raw)               # -> HL7Message (segments preserved)