How to read an HL7 v2 message

This page takes one real message and reads it from the first line to the last value.

It takes about ten minutes. Keep a message of your own open beside you as you work through it.

1. Start from a message

An HL7 v2 message is plain text. Each line is a segment. It starts with a three letter code saying what the line is about. Everything after that code is fields, separated by |.

An admission message. Four lines, four segments.

MSH|^~\&|EPIC|STJOSEPH|LABSYS|STJOSEPH|20240314093015||ADT^A01^ADT_A01|MSG00017|P|2.5.1
EVN||20240314093000
PID|1||1000345678^^^STJOSEPH^MR~453-22-9911^^^USA^SS||CARTWRIGHT^ELEANOR^MAY^^^^L||19510822|F||2106-3|41 ORCHARD LANE^APT 2B^PORTLAND^OR^97202^USA^H||^PRN^PH^^1^503^5550142|^WPN^PH^^1^503^5550188|eng|M|CHR|100034567800
PV1|1|I|3W^312^A^STJOSEPH||||1447312^OKONKWO^ADAEZE^^^^MD|||MED||||1|||1447312^OKONKWO^ADAEZE^^^^MD|I|V100034567|SELF|||||||||||||||||||SJ||A|||20240314093000

Read the first three letters of each line and you know the shape: a header, an event, a patient, a visit. Everything else hangs off those.

Inside a line, four marks split the text into smaller parts. Each mark means one thing, and they always mean the same thing:

PID|1||12345^^^HOSP~98765^^^SSA||DOE^JOHN||19510822|M|||5 Elm St&Apt 2^Boston

Segmentthe three letters that start the line and say what it is about
Fieldeverything between two | marks, however many parts are inside it
Repeatthe same field given again, separated by ~
Componenta part of a field, separated by ^
Sub-componenta part of a component, separated by &

A PID line, with each level marked. Empty positions are normal: a sender fills in what it has.

2. Read MSH-9

Every message begins with an MSH segment, and its ninth field is the one that tells the receiving system what it has just been handed. Fields are counted by the | separators between them.

That single field answers three separate questions, and the answers are separated by ^:

MSH-9 shown as ADT caret A01 caret ADT_A01, with each part labelled beneath: message code, trigger event, message structure. — MSH-9 taken apart, from the ADT page. Every message type page shows its own.

ADTthe message type: what kind of message this is.
A01the trigger event: what happened in the real world to cause it.
ADT_A01the message structure: which segments to expect and in what order.

The last two look like they should always match and often do not. One structure usually serves several events, so ADT_A01 carries A01, A04, A08 and A13. The structure tells you how to parse the message; the event tells you what to do about it. A receiver that switches on the structure alone cannot tell those four apart.

3. Find the segments

Take the message type from MSH-9 and open its page, for instance ADT. Each structure is listed with every segment it carries, in order, and whether each one is required.

The cardinality column is the one to read. A segment marked 1..1 must appear exactly once; 0..* may appear any number of times including none. Required inside an optional group means required only if you send the group at all, which is the single most common misreading.

4. Read a segment page

A segment page lists every field the standard defines for it. The columns are the standard's own, in its order, so you can hold the specification open beside this page.

The PID field table, showing columns for sequence, length, data type, usage, repetition, table number, item number, element name and cardinality. — The field table on PID.

SEQthe field's position, so PID-3 is the third field.
LENhow long the value may be.
DTits data type, linked to what that shape holds.
OPTwhether you must send it: R required, O optional, C conditional, B kept for backward compatibility.
RP/#whether it may repeat.
TBL#the code table its values come from, where there is one.
ITEM#the standard's own identifier for the field.
CardinalityOPT and RP/# combined into one number the standard does not print. The header links to how it is derived.

5. Look inside a field

Many fields are not a single value. PID-3 is a patient identifier list, and an identifier is made of an ID number, an assigning authority, a type code and more. Click the field number to open what is inside it.

The PID-3 row expanded, showing the ten components of the CX data type with only the ID number marked required. — `PID-3` opened. Ten components, of which only the ID number is required.

Components are separated by ^ inside the field, and addressed with a dot: PID-3.1 is the ID number. Only fields with something inside them open; a field holding a single value has no arrow.

6. Follow a coded field

Where a field has a number in the TBL# column, its values are not free text. That number links to the table of codes it may carry.

Table 0004 patient class, listing its codes beside their meanings. — Table 0004, the values `PV1-2` may carry.

Whether a code outside the list is an error depends on the kind of table, and the difference matters more than it looks. An HL7 table is fixed by the standard and an unrecognised code is a fault. A user-defined table is only a suggestion, so a site may extend or replace it, and a validator that rejects anything unlisted will reject real traffic. Each table page says which it is.

How to use these specifications covers the other half: the navigation, the search and the parts of a page you can click.