HL7-Definition V2

Hello HL7 community, we’ve decided to give the old HL7-Definition reference website its well-deserved retirement. We’re now proud to introduce the new and improved HL7-Definition V2 website.

We’ve been asking for your feedback for the last few months, and for a good reason :-). By popular demand, we’ve included some new features, including: 

  • More detailed specification descriptions
  • Standard HTTPS, removing the need to use custom ports
  • A more convenient and user-friendly search feature
  • Improved overall performance
  • Mobile friendly

Coming soon

  • Offline support
  • Message decoder – See field names in HL7 messages
  • Message validator – Validate the message is inline with the standard
  • FHIR specification support


You can find it here: https://hl7-definition.caristix.com/v2



 The Caristix team!

HL7® Definition Reference

EDIT [2019-11-07]

Hello HL7 community, we’ve decided to give the old HL7-Definition reference website its well-deserved retirement. We’re now proud to introduce the new and improved HL7-Definition V2 website.

We’ve been asking for your feedback for the last few months, and for good reason. By popular demand, we’ve included some new features, including: 

  • More detailed specification descriptions
  • Standard HTTPS, removing the need to use custom ports
  • A more convenient and user-friendly search feature
  • Improved overall performance
  • Mobile support


Coming soon

  • Web-application installation
  • Message decoder and validator
  • FHIR specification support

HL7-Definition V2

Caristix is pleased to make the online HL7® Definition reference available to all users. It’s an easy-to-use complete reference. Just chose the HL7® standard you need to use (the default is v2.51) from the drop down menu. Next, choose the trigger event, segment, data type or table, or enter a search string to get the needed definition.

You can find it here: https://hl7-definition.caristix.com/v2

While you are on our website, check out our Workgroup demo. Workgroup is our team focused solution for the development and delivery of interfacing projects.

Note: HL7 and Health Level Seven are registered trademarks of Health Level Seven International.



What the data in HL7® messages can tell you


You already know that HL7® messages are a rich source of actionable insight about your clinical and financial operations.

To get to that insight, start by inspecting, analyzing and querying your messages. You can do this manually via text editors and their basic search features. Or you can check out Caristix software.

Here are some HL7® message inspection and analysis tutorials to get you started using Caristix Pinpoint software. And get your data working for you.

Download Pinpoint

To use these tutorials, download a trial version of Pinpoint.

Once you’ve installed Pinpoint, launch the application. Get ready for these tutorials by loading HL7® messages; learn how in our Online Help.

Tutorial 1: Determine field position

What to do

Hover over a field to view its HL7® position.  Use this feature when you’re assessing where a field or nested subcomponent might fit in a message.


You’re looking up a patient address in the PID segment. Don’t count pipes. Just hover over the address, and “PID11.3 Patient Address > City” pops up.

Tutorial 2: Check field names and values

What to do

Load messages, then right-click a segment to see the full HL7® definition (click “Segment Definition”). Use this feature when you need to check field names and values at a glance.


You’re looking up a PV1 segment in a message. You’re looking at Admit Sources. Rather than counting over to PV1.14, just get the Segment Definition and check SEQ 14.

Tutorial 3: Troubleshoot empty fields

What to do

Find an empty field or component in a problem message, as follows:
1)    Load messages and hover over the field (or component) you want to query.
2)    Right-click and select Add Data Filter.
3)    Change the Operator to Empty, and click once outside the grid. You’ll get all the messages with empty values in that field.


You have 24 hours of messages to look through, and you need to identify empty PID-8 fields. Set a filter (as above) in a few mouse-clicks. It’s much faster than counting pipes and carets.

Tutorial 4: Determine field presence

What to do

Find out if a field is present in a batch of messages – and how often the field occurs. This is helpful when you’re troubleshooting complex interfaces.
1)    Load message logs and hover over the field (or component) you want to query.
2)    Right-click and select Add Data Filter.
3)    Change the Operator to Present, and click once outside the grid. You’ll get all the messages with fields that are present.


You have 24 hours of messages to look through, and you need to identify which messages have ZCD-23 fields. Set a filter as above, and avoid scripting.

Tutorial 5: Isolate the right data values

What to do

Look up values and isolate the data you need. Use the Data Distribution feature to look up values.
1.    Load messages and hover over the field you want to query.
2.    Right-click and select Data Distribution.  Click Show All, then Table View.
3.    You’ll get all the values in that field and the number of times they were used. Copy values to Excel or Word as needed.


You need to set up lookup tables for a new interface. You could port all the old values from the legacy interface engine. But this would include many out-of-date codes. Instead, get a batch of messages from the current engine, and perform a Data Distribution in Pinpoint to get the currently used values.

Caristix Pinpoint for HL7® Message Analysis

We hope you find these brief tutorials helpful. Let us know how they’re working for you in the comments!

Download Pinpoint

What is Reverse-Engineering?

Why consider reverse-engineering? Lack of accurate specs


If you’ve worked on an interfacing team or for HIE, one of the issues you’ll hear about is a lack of accurate interface specifications. For instance, the vendor spec might be missing. Or the source or destination spec on hand might no longer match the production version.

So what do you do?

Lack of specs: what’s the impact on your ability to deliver?

Well, you might be facing weeks of digging and research. You’re missing a lot of information about the source and/or destination system you’re interfacing. You and your team will have to spend time getting that information, either in a series of kickoff and liaison meetings with the customer, or going back and forth with whichever application team is responsible for the system. And in a worst-case scenario, you’ll get piece-meal information that will allow you to get rough-draft style interface in place, and spend weeks testing and tweaking until it works.

If you’ve been through this process, you know that weeks can drag into months.

What if you could skip all that?

This is where reverse-engineering comes in.  So just what is reverse-engineering?

Reverse-engineering: create your own specs

Reverse-engineering is a technique and technology that we developed and incorporated into the Caristix platform. In a nutshell, reverse-engineering allows you to take sample messages from a source or destination system, and create a spec in a matter of minutes.

Reverse-engineering gives you a full list of application-specific elements and attributes:

  • Message types
  • Segments, including z-segments
  • Fields
  • Data types, including custom types
  • Code sets, including custom elements
  • Message-specific code sets (ability to differentiate field content A01 vs A08 messages, for instance)

What this means for your work

We’ve listed the data elements you obtain via reverse-engineering. Having them at your fingertips can transform how you and your team work.

Take code sets, for instance.

If you’re creating a lab interface, you’re probably working with a set a set of customized code sets. And these may change from time to time. Without reverse-engineering, you’d have to ask the lab system application manager to pull these codes manually. With reverse-engineering, you’d pull these codes automatically from the data itself – and the list would be complete.

That’s the advantage of reverse-engineering. A complete list of the structure and content elements. A lot less trial and error. And faster time to implementation.

Further resources

If you’d like to do a deep dive on Caristix reverse-engineering capabilities, check out the product help documentation:


To see how reverse-engineering works, check out the video below.

See the whole Caristix platform in action in our 16-minute on-demand demo.

HL7 Interface Documentation, Scoping, and Sample Messages, Part 2

In a previous post on interface documentation and sample HL7 messages, I touched on four guidelines for using sample messages. We’re working on software that will make it easier to use sample messages effectively in your HL7 integration projects. The software is called Caristix Reader, and it will be available free of charge upon release. A beta version is now available for download and evaluation here.

Caristix Reader and Sample HL7 Messages

1. Message Structure
Caristix Reader captures message structures from sample messages. So you won’t have to look up z-segments or count pipes to find the right Patient ID field.

2. Message Content
Caristix Reader captures message content and data values from sample messages. So you have a list of values from key fields such as OBX.2 and OBX.5.

Maximizing Value from Sample HL7 Messages

Use a large sample.
If you can, grab at least 3 days of messages. A week’s worth would be even better. Caristix Reader loads HL7 logs and generates a spec containing the message structure and content.

Filter the HL7 messages you need.
Message logs can be noisy. They might contain test messages or messages from systems that aren’t relevant to the interface you’re building. Caristix Reader lets you keep just the messages you need.

Share your knowledge.
Once you’ve extracted the message content and structure, Caristix Reader lets you share as much as of this information as needed. Copy portions to Excel or Word, or send a complete HL7 profile to another Caristix Reader user.

Learn more about Caristix Reader here.

Download the free beta version here.

HL7 Interface Documentation, Scoping, and Sample Messages, Part 1

When it comes to interface documentation formats, we’re all about using whatever analysts, project managers, and developers find helpful: Word site surveys, Excel lists, wikis, whatever works. Those tools are perfect for handling the baseline information around inbound and outbound channel specifications and transport specifics.

In recent customer conversations and in discussions on LinkedIn, one practice stood out: the use of sample messages to understand real-world systems. Sample messages contain a wealth of information about the systems that need to connect. We recommend the use of sample messages as an interface scoping best practice.

Here is what sample messages can tell you:

Message Structure
There’s the ideal HL7 specification that a vendor provides, and then there’s real life. Once a product goes live in a healthcare provider setting, chances are its HL7 attributes have shifted from the original application spec. And as a provider’s HIT ecosystem evolves over time, the HL7 attributes shift again. You end up with new z-segments, changes to fields, and changes in coded values. Sample messages give you a snapshot of the system as it is today — the real thing you’ll need to interface. Sample messages give you up-to-date, real-world message structures to work with.

Message Content
Hardly anyone documents data values in messages. Yet, how great would it be if you had a list of OBX.5 values at your fingertips when you’re building an LIS interface? Sample messages can do that for you. They can provide you with a list of values a facility uses. They can even tell you which values are used the most. Using message content, you’re no longer relying on someone else’s memory to get the right information.

4 Guidelines for Getting the Most out of Sample HL7 Messages

If you decide to include sample messages in your documentation package or site survey process, keep the following in mind:

1. Avoid small message batches.
If you work with just a handful of messages, you might not capture enough data to cover the major workflows. For instance, when you’re integrating with a lab system, the OBX.2 Value Type field is important. Maybe your lab system only transmits text. Then you’re in luck: you don’t have to do a deep dive through the sample messages, but chances are the system will not send other value types. Your sample set needs to be large enough to cover all the various cases. Also, what if you’re dealing with multiple systems — or multiple value types? In one integration project we worked on, the vendor had to connect to multiple lab systems. One lab provider delivered OBX values as text. Another lab provider had multiple types: text, images, PDFs, encapsulated data, numeric values, and strings. If our sample had been limited to 10, 20 or 100 messages, we probably wouldn’t have caught all of the different value types. We would have had to wait until the validation phase to catch errors through trial and error, which would have delayed the project.

2. Aim for a manageably large sample.
And that brings us to a second point: what happens when you have a week’s worth of sample messages or more? First, this volume will give you enough content to work with. But if you’re working manually (or with a limited HL7 tool) this many messages may be difficult to sift through. If the batch is big enough to be useful for extracting information about site-specific details, it’s likely to be too big to review manually. You don’t want to be stuck counting pipes.

3. Share the right messages.
When you extract a big batch of sample messages, chances are you’ll end up with some noise. You’ll want a way to filter out messages that aren’t relevant to the interface you’re working on. Filter out messages from sending applications that aren’t part of the interface (or provide filtering information) before providing sample messages.

4. Share the right messages at the right time.
Systems change, and interfaces change. The sample messages you grabbed 3 months ago might be different than today’s batch. Make sure you use recent messages, and if the project iterates over multiple phases, update your sample messages along with the data you extract.

Do you have any other advice for using sample HL7 messages when building an interface? Please share in the comments.

In an upcoming post, we’ll cover Caristix Reader, the software we’re creating to read sample messages.

Why Do HL7 Interfaces Take So Long to Write?

HL7 Interfacing Advice from the Indiana Health Information Exchange

The largest health information exchange (HIE) in the US is located in Indiana. It connects 80 hospitals, and serves 10 million patients as well as 19,000 physicians. IHIE members participated in a recent meeting of the Central Indiana Beacon Community and posted their slide decks here. The presentation that resonated for us was Mapping Interfaces by Dr. Mike Barnes, Dan Vreeman, and Amanda Smiley (PDF).

Their killer quote: “Interface programmers are the only barrier between a successful interface implementation and your organization appearing on the front page of your local paper.”

That’s part of the reason HL7 interfaces take so long to write. The authors also say that it’s not just about the writing, the coding, or the configuration. It’s about understanding the interface: scoping, gap analysis, and sometimes, getting the buy-in to change source systems. Their deck included a useful 9-step overview of the HL7 interface development process. Here it is, along with a few comments from us:

1. You have to get examples (+/- specs).
Get as many examples as you can. Cover as many HL7 messaging and workflow scenarios as needed. And get those interface specs if you can. But keep in mind they might be out-of-date.

2. You have to study them (in detail).
Study everything in detail. Make sure you have a system to track your findings. Have a repeatable gap analysis process to cover the examples and logs you might get. Just because one system is using PID segments as a primary patient identifier, doesn’t mean that another system won’t be using PV1 segments. For a deeper dive, we’ve got a white paper on HL7 integration and gap analysis.

3. You discover problems, or have questions.
Have a process for dealing with them. It’s not always easy because interfaces, HL7 messages, and system workflows are so disparate. What you learn with one provider’s EMR won’t port over to another provider’s system.

4. Request fixes or answers to questions.
It helps to document your problems and then those fixes.

5. Time passes (days to weeks).
You bet it does. That’s why it helps to document it all.

6. You forgot the details of the interface (Rpt #2).
There are those pesky details again. Documentation (and the ability to share) can really help.

7. Fix problem or resolve questions.
This is on-going. When you think you’re done with an interface after the go-live, it’ll come back to haunt you once one of the sending systems is tweaked. You’ll need troubleshooting tools and processes to account for changes.

8. Repeat steps 3-7 until interface is ready to write.

9. Write interface.
By now, writing the interface is a piece of cake. Especially if you’ve got solid integration technology that makes the actual writing easy.

The key takeaway… You can have the best interfacing engine in the world, the HIE infrastructure with the most bells and whistles, and the coolest SOA and ESBs. But a good interface starts with an analyst’s ability to dig into the details and document her findings.

Read the rest of the Mapping Interfaces PDF deck on the Indiana Health Information Exchange site.

Guest Post on Healthcare IT Guy

Jean-Luc Morin, VP R&D at Caristix, has a guest post on Shahid Shah’s blog, Healthcare IT Guy. Shahid’s top-ranked blog covers healthcare IT, EMR, EHR, PHR, medical content, and document management.

Jean-Luc’s article covers 6 questions hospital CIOs and IT directors should be asking vendors about interface documentation.

Here’s an excerpt:

At first glance, documentation doesn’t seem like a CIO-level concern. In a typical implementation cycle, the team gets a few specs from a vendor. Someone signs off on an interface configuration document. Then you implement and go-live. The role of documentation in the larger scheme of things? Seems like a project management checkbox at best.

But it isn’t.

Your vendor’s interface documentation practices can have a major impact on the speed and success of implementation and on the maintainability of your new system after go-live.

Go read the rest here…

Will HL7 V3 Adoption Take Off in 2011? 5 Points and 1 Caveat

A few weeks ago, I was working on an HL7 v3 project with an outside partner and the discussion turned to market adoption. We came to the conclusion that it’s not exactly taking off — at least, not as quickly as you might expect. Apart from meaningful-use initiatives around CDA in the US and the big push by Canada Health Infoway, I don’t really see much traction in North America. I’m going to come right out and say this: from a vendor perspective, the incentives to embrace the new standard are just not there in 2011.

My thoughts were kicked off by a post from HL7 guru René Spronk. René wrote that the focus to date has been on modeling and that implementation-related material is missing. René also listed 5 improvements that would help implementers adopt HL7 v3. He raises some great points. Even if the post is almost a year old, the list still holds… In a large volunteer organization like HL7, there are no quick changes.

So what exactly is limiting HL7 v3 adoption? To build on René’s list, here are a few more points to consider.

1. Cultural Hurdle: HL7 V.3 Implementation Needs a Change in Mindset

HL7 v3 is a completely different standard than HL7 v2.x. Because HL7 v3 isn’t backward-compatible, when you migrate, you need to change the way you look at interfaces. In the HL7 v2.x world, many analysts treat HL7 messages as strings of data elements. They see their key task as follows: look for the data, find it in the “right string”, and map the string to the right data element in the new system under deployment. What about the semantic gaps, you may ask? The answer in this world: we’ll worry about them during system validation and patch in a workaround. What’s more, in this world, message schemas are manually specified in Microsoft Word documents much of the time.

So from a provider perspective, HL7 v3 is going to demand a change in mindset. The message schema is programmatically specified and modified (if needed). If you’re a big Word fan, you’ll probably have a hard time finding your schema in a familiar format. Most likely, you’ll be encountering a new set of tools for data element mapping. This is a big shift from business-as-usual in the HL7 v2.x world.

2. Steep HL7 V3 Learning Curve

Interface analysts in the HL7 v2.x world are a mixed bunch. Some come from the clinical side of the business, others from the development side. A surprising number are non-technical (which is terrific — we need a range of skill sets in our industry). This works fine for now, since the HL7 v2.x format is quite straightforward. At a minimum, as long as you’re able to count pipes and basically grasp the data being exchanged, you’re good to go. You can start quickly with minimal training. With some help from basic open-source or home-grown tools, you don’t really need deep technical knowledge.

But migrate to HL7 v3 and the game changes. Again, you need a new mindset. The technical skills are different and the way you build or configure interfaces is different as well. Just take a look at this HL7 v3 primer. It’s perfect if you want to understand where the standard comes from. But it’s far too complex if all you need is to learn how to configure an interface. So there’s a learning curve, and it’s not just for analysts. Implementers need to create new material to support analyst learning. And that won’t happen overnight, especially if the market is slow to materialize.

3. No Clear Benefits for Most Healthcare Systems

Healthcare systems have been using v2.x interfaces for decades. Sure, the standard and related processes are issue-laden, and the typical interface deployment process is bumpy at best. HL7 v2.x is far from perfect. It’s probably more expensive and intense to run an HL7 v2.x environment than a future-state HL7 v3.

But most organizations have learned to live with these faults. For most organizations, HL7 v2.x works. It feels safe. It’s become standard business practice.

So HL7 v3 comes along. It’s unknown. And the unknown feels risky, right? Very few healthcare systems are going to jump in with both feet as long as the ROI remains elusive. From what I’m seeing in the field, organizations are not rushing to spend money to fix what amounts to a non-broken process.

The Caveat: CDA and Document Exchange

Despite what I said about the unknown, there is a pretty encouraging caveat to all this. And that is the push for CDA templates and the need for document/data exchange. This is new, and driven by meaningful use in the US, so organizations have to act. HL7 v3 seems to be answer here, and I predict greater adoption related to data exchange.

4. HL7 V2.x Compatible Interfaces Still Needed

Obviously, supporting HL7 v3 doesn’t mean you’re going to be done with HL7 v2.x. HL7 v2.x interfaces are going to stick around, well into any foreseeable HL7 v3 future. Some will start by integrating v3 components, but vendor and hospital infrastructures will remain HL7 v2.x centric over the course of migration. Even if the upgrade benefits were clear, the process could take over 20 years. Meanwhile, related HIS technology will keep rolling along and evolving, and vendors would get stuck with even more to support.

5. Missing Tools

As we speak, the HL7 v3 toolset is thin on the ground, compared to the rich pickings in the v2.x world. We need a more robust toolset in order to get to the productivity levels and skill sets that HIT vendors and healthcare providers expect. Tools will emerge as adoption grows. But for now, the missing toolset is yet another risk for early adopters to manage.

What’s Next for HL7 V3?

Now that I’ve said my peace, don’t get me wrong.

HL7 v3 is an elegant step forward in healthcare system interoperability. But the design quality of the standard isn’t a compelling migration driver. We’ve been using HL7 v2.x for so long that we’re used to its weaknesses. For us to shift, we’re going to need stronger, clearer market drivers. Change — even good change — is risky within organizations. We shouldn’t underestimate our own reactions to risk.


Readers, what are your thoughts? Does HL7 v3 adoption touch a nerve? Let’s hear it in the comments.