Design HL7 V2 Message

In the previous lesson, we looked at the structure of an HL7 v2 message. Now let’s put that knowledge into practice by building a message on our own.

We’ll use the HL7 v2.5.1 specification to understand the message structure and the Medblocks HL7 v2 Message Editor to build the message.

You can clear the message from the body of the editor if it has a pre-loaded sample message as we are going to write our message from scratch. You can also insert a sample message body by clicking on the Create a message button.

For this exercise, we’ll build a basic Patient Admit (ADT^A01^ADT_A01) message with just required segments and fields. If you want to keep optional segments and sample values, toggle their respective buttons and click on the Create message button.

The message template has a pre-filled mandatory MSH segment’s field for your convenience.

The specification tells us which segments and fields are required, optional, or conditional. So, you do not need to memorize these details. In real-world HL7 v2 work, the specification is commonly used as a reference.

Designing a Patient Admit message

The ADT message with A01 as trigger event for patient Admit/Visit Notification has four mandatory segments - MSH, EVN, PID, PV1. We will start working on each of them one by one.

MSH - Message Header

Every HL7 v2 message starts with an MSH (Message Header) segment. It contains information needed to interpret the message, including the message type, timestamp, processing ID, and HL7 version.

As you can see in the specs, the MSH segment has MSH-1, MSH-2, MSH-7, MSH-9, MSH-10, MSH-11, MSH-12 as the required fields.

The beginning of the segment is:

MSH|~\&

Here MSH is a segment identifier. The MSH-1 is the pipe character ‘|’. It is also the field separator, while MSH-2 defines separators such as ^, ~, \, and & for the components, repetitions, escape sequences, and subcomponents in this message. Both of them are required fields.

The MSH-3 or the Sending Application and MSH-4 or the Sending Facility values are also pre-filled, but these are optional fields. You may choose to remove their values.

The next required field is MSH-7 which is the timestamp for Message creation time.

Then the next required field is MSH-9 which is the Message type. This field has further 3 required components. MSH-9.1 is the message code. MSH-9.2 is the trigger event and MSH-9.3 is message structure.

Then we have MSH-10 which is the Message Control ID.

The next one is MSH-11 is the processing mode where P is for production

And the last required field is MSH-12 which is the HL7 version.

With this we have finished writing our first segment. The next one is Event Type or EVN.

EVN - Event Type

The EVN (Event Type) segment contains information about the recorded date and time of the event.

As you can see in the specs, only EVN-2 is the required field. So, we’ll use 2026080409230 as the Recorded Date/Time.

It’s worth distinguishing this from MSH-7. MSH-7 represents when the message was created, while EVN-2 represents when the event was recorded.

Now, we have completed two segments but still there is no trace of any patient details in the message. That is when we will move to the next required segment which is the Patient Identification segment.

PID - Patient Identification

The PID (Patient Identification) segment identifies the patient and contains demographic information. The specs tell us that PID-3 and PID-5 are the two required fields for this segment.

Here, we will use 12345 for PID-3 which is the ID Number of the patient identifier. And for PID-5, we will have DOE as the family name and JOHN as the given name and together they represent the patient’s name.

We have completed writing 3 out 4 required segments at this point. And we just need info about Patient Visit which is the PV1 segment.

PV1 - Patient Visit

The PV1 (Patient Visit) segment contains information about the patient’s encounter.

From the specs, we know, just PV1-2 or Patient Class is required. We’ll use `I` which indicates an inpatient encounter.

So, with that our message is completed. We can now read this message as a clinical event which says “An inpatient admission event was recorded for John Doe on August 4, 2026 at 09:23:00 AM.”

This is a very simple ADT message and the real-world messages can contain many more segments and considerably more information.

Other common segments

HL7 v2 defines many segments for different types of healthcare information. Some common examples include OBR or Observation Request, OBX or Observation/Result, NK1 or Next of Kin / Associated Party, IN1 or Insurance, ORC or Common Order.

The segments used depend on the message type and the workflow being represented.

In the next lessons, we have an exercise for you!