# Parsing Hl7v2 Messages

Decodes pipe-delimited HL7 v2.x messages (ADT, ORU, MDM, ORM) into structured...

- Repository: https://github.com/maziyarpanahi/openmed (5755 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add maziyarpanahi/openmed --skill parsing-hl7v2-messages -g -a claude-code -y`
Codex: `npx skills add maziyarpanahi/openmed --skill parsing-hl7v2-messages -g -a codex -y`
Cursor: `npx skills add maziyarpanahi/openmed --skill parsing-hl7v2-messages -g -a cursor -y`
Gemini CLI: `npx skills add maziyarpanahi/openmed --skill parsing-hl7v2-messages -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add maziyarpanahi/openmed`

## Description

Decodes pipe-delimited HL7 v2.x messages (ADT, ORU, MDM, ORM) into structured segments/fields/components and surfaces OBX-5 and NTE-3 free-text narrative for OpenMed. Use before OpenMed processing when ingesting HL7 v2 feeds from an interface engine, lab/results system, or ADT stream and you need the embedded clinical note text de-identified and analyzed. Flatten OBX/NTE text then call openmed.deidentify and openmed.analyze_text; segment-aware redaction is available via openmed.interop.hl7v2. Trigger keywords: HL7, HL7 v2, ADT, ORU, OBX, MSH, PID, pipe-delimited, interface engine, Mirth, lab results.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```python
import openmed
from openmed.interop.hl7v2 import parse_hl7v2

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

The rest: https://github.com/maziyarpanahi/openmed/blob/HEAD/skills/parsing-hl7v2-messages/SKILL.md