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.



HL7® Specifications: The Basics

What is an HL7® specification?

HL7 specification standard
HL7® specification standards

 No matter how many interfaces you are integrating, a critical step is the definition of your HL7® interface specifications.

A formal definition from HL7 International in the v2.5 standard definition states:

“An HL7® message profile (or HL7® specification) is an unambiguous specification of one or more standard HL7® messages that have been analyzed for a particular use case. It prescribes a set of precise constraints upon one or more standard HL7® messages.”

In other words, HL7® specifications or a profile describe the data and messages that an interface sends and/or receives. The description must be clear and precise enough so that it can act as a set of requirements. Each integration project needs a spec for each inbound and outbound interface. Without the spec, you’ll waste lots of time trying to figure out what’s going on through trial and error.

HL7 specification syste Basically, an HL7® specification describes:

  • Trigger events supported
  • Data format (segments, fields and component descriptions)
  • Data semantics
  • Message acknowledgment responsibilities

With the spec, you’ll be able to:

  • Get analyst, developers, internal customers, vendors, and consultant all on the same page.
  • Identify risks before interface development.
  • Eliminate time lost spent determining requirements, testing, and fixing issues during go-live.
  • Develop the interface documentation you can share with your team and your client.
  • Easily generate your gap analysis report and test and validation report.

For more information on HL7® specifications, check out Chapter 6 of our Survival Guide.

HL7® Specification Template

To get you started, we’ve developed the HL7® Specification Template. You’ll find both Excel and Word documents included in the zip file. Download it here.

In the Caristix world, you can generate gap analyses, documentation, test plans and validation reports using Caristix Workgroup and cut interface development time – and cut waste from the entire interface lifecycle.  Learn more via the Caristix Workgroup on-demand demo.

5 key interface lifecycle concepts

Inteface lifecycle concepteLast week, we talked about how you can do more with less by applying a lifecycle approach  to your interface and interoperability work. By managing the lifecycle (instead of developing via trial and error), you’re able to forecast timelines, resources, and costs with more accuracy – and better outcomes and margins.

Start by getting a firm grasp on the key interface lifecycle concepts behind interface lifecycle management. This post will give you a solid foundation.

HL7 requirements

You need requirements thinking to build an interface. In other words, you document the needs that the interface must meet: messages, content, format, workflows. Sounds simple, right? Not really. Traditional requirements-gathering leads to trial and error pain, slowing down both system and interoperability implementations.

Learn about the right way to gather HL7 requirements. 


HL7 requirements include accurate specifications of the systems you plan to connect. What do you do if the vendor spec is missing? Or if a PDF spec no longer matches the production version? There’s a way to generate the spec automatically from production messages, so you get a list of system-specific attributes such as message types, segments, fields, data types, and code sets. It’s called reverse-engineering, and it’s a technique that we developed at Caristix.

Learn about reverse-engineering and how it can impact your interface development.

Gap analysis

Another requirement document you need for building an interface is a list of gaps the interface will bridge: a gap analysis. A good gap analysis will map differences in message structure and content in the source and destination systems. You can either do this work manually or use automated software to speed the process and gain accuracy.

Learn about gap analysis.


De-identification is a technique to mask or remove PHI from patient data. Surprisingly, it’s a life-saver in HL7 interfacing. You’ll want to consider de-identifying HL7 messages whenever you’re faced with troubleshooting a system or interface, populating a test system with realistic messages, and gathering data for analytics.

Learn about de-identification.


Validation is about checking the interface: does it meet the requirements you captured at the start of the project? Traditionally, validation is done manually: creating test messages, sending them, and checking the workflow. But manual work can be a recipe for disaster, which is why we recommend automating validation and testing tasks.

Learn more about validation and automation.

Other concepts?

Can you think of other concepts we should cover in an upcoming blog post? Leave a comment to let us know.

For a review of the key phases of interface lifecycle managment, check out our last blog post, Interface lifecycle managment: do more with less.

Interface lifecycle management: do more with less

Caristix white paper lifecycle managment
Caristix White Paper: HL7 Integration: From Trial and Error to Predictable Project Outcomes and Margins

If you’re responsible for interfacing within a hospital system, a consulting organization, or an HIE, you know one thing: you need to do more with less. With EHR implementations slowing down, the big HIT implementation budgets are drying up. But so much of the promise and value of those systems is tied to interoperability and data exchange, and you’re still accountable for delivering those capabilities. So what do you do?

In this situation, you want to consider a lifecycle approach to your interoperability programs. Interface lifecycle management removes waste from the work by getting rid of ad hoc processes. You’ll be able to do more with less, and as a result, sustain your operations and meet demands for interoperability more easily.

The major phases and potential pitfalls

We’ve outlined the major phases of the interfacing lifecycle below, along with the some of the pitfalls you might encounter.


In the scoping stage, the first step is to understand what systems are in place, what data is available, when it is available, and in what format. Management may underestimate the amount of effort for this phase, since people who not hands-on assume the HL7 standard helps streamline this process. But the standard is such a loose framework that, used on its own, it leads to a lot of trial and error in the next phases. The lifecycle really starts with strong requirements-gathering practices right here in the scoping phase.


The next step is to configure or code the interface, or build a bridge that connects two systems. In most cases, developers use an interface engine to handle the mapping and transformation. Even with the use of an interface engine, your team will need good requirements from the scoping phase in order to eliminate waste during this phase.


In the validation phase, developers (or quality testers) test the interface before it goes into production. If the underlying requirements from the scoping phase aren’t strong, the configuration and subsequent validation will be subject to multiple trial and error cycles – wasted time and effort. What’s worse, you may not discover gaps until the system is in production, affecting data quality, user adoption, and potentially quality of care. From a project management point of view, you also can’t predict the project end-date because it’s impossible to anticipate the defects testers will uncover.

After Go Live, support and maintenance

Is the data flowing as expected? Are new bugs emerging? Use the work your team did in the scoping, configuration, and validation phases to manage and maintain the interface. If you’ve got multiple interfaces, make sure the work from previous phases is readily available to consult in a shared repository. Those requirements from the scoping phase are especially important.

Upgrade decision

Whenever your leadership decides to proceed with a version upgrade of a source or destination system, you’ll need to evaluate the impact on the interfaces that connect those systems. In most cases, an upgrade will mean you start the interface lifecycle all over again. Without the artifacts – requirements, tests, queries – from the previous cycle, you’ll be starting from scratch.

Download white paper on interface lifecycle management

Learn more about interface lifecycle management in this whitepaper from Caristix: HL7 Integration: From Trial and Error to Predictable Project Outcomes and Margins. You’ll get a deep dive on the phases we touched on above, and you’ll come away with a better understanding of the collaboration and operational benefits of adopting interface lifecycle management.

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

Need HL7® message samples? Google isn’t the answer

HL7® message samples should be system-specific   

HL7 messagesWhen you build interfaces, you need HL7® message samples and test messages for your validation workflow. It’s tempting to simply hit Google for generic samples, or check on Stack Overflow or another tech discussion forum. But there are problems with that approach.

For one thing, you’ll end up with messages that don’t fit your systems – your ADT, your LIS, the applications personalized for your environment. What’s more, if you use just a handful of messages, that volume won’t be enough for thorough HL7® interfacing testing.

The danger with shoddy testing practices

Without the right messages and the right volume, you won’t be able to validate that events are exchanged appropriately, code sets are transmitted or transformed correctly, and optionality is handled as expected. What’s worse: if these validations tasks are skipped, developers can spend hours or days in a break-fix cycle during go-live.  

Need HL7® Message Samples? Consider 3 Solutions

  1. Create them manually. You can always extract a handful of production HL7® message samples, remove the PHI manually, add dummy patient demographics, and use those messages in your testing. But this is painstaking and error-prone. And you won’t solve the volume problem for performance testing.
  2. De-identification. Many of our clients use their production data for testing and validation. But before they do, they remove PHI and replace it with clinically valid fake data.  Read more about de-identification here.
  3. Test automation. Our clients also use test automation software to generate HL7® message samples. Test automation software (such as the Caristix solution) can generate messages on the fly, based on interface specs representing both source and destination systems. Learn more about test automation here.


Mix Them Up

Depending on your needs, you may need a mix of these techniques. If you have time and a tiny use case, consider manually creating your messages. If you have established production-based applications, de-identifying messages from those systems will work for you. And if you’re connecting brand-new systems, you’ll want to include messages generated via a test automation solution.

Caristix Workgroup

The Caristix platform includes features to de-identify messages and automate your tests while generating messages on the fly. Learn more today with the 16-minute on-demand demo of the Caristix Workgroup platform.

HIEs and Interface Testing

Interoperability barriers and HIE business models

HIEs and interface testingIn a previous post, we talked about the interoperability barriers facing HIEs (healthcare information exchanges). What are they? Primarily 1) cost and 2) complexity. That is, the cost of interface development, and the technical difficulty involved. These are especially in context of the business model switch, as HIEs move from startup grant-based funding to self-generated revenue based on membership fees and services.

The problem is, self-generated revenue is tricky to achieve at best. In some cases, the fees barely cover costs. So how do smart HIE leaders make it work? For one thing, they aren’t focused on cutting headcount (because in many cases, these are lean operations), but they are focused on speed and quality. They drive down cost by increasing speed to interface delivery without sacrificing quality.

Why requirements are critical

They increase speed and quality both by ensuring that their interfacing teams focus on requirements. Not just any requirements – the right requirements. The right interfacing requirements, gathered at the right time, set the stage for clearer communication and expectations.

Read more about HL7 requirements.

How to reduce costs while increasing speed and quality

Good requirements are one side of the interface delivery coin. The other side: testing. Once HIE leaders have put in place a strong requirements culture, they tackle interface testing and validation, which is the process of ensuring that the interface works per the requirements.

Read more about what can wrong with HL7 interface validation. It applies to HIEs and their interface testing.

HIE leaders focus on testing and validation because the interfaces they deliver must broker key workflows between partners: hospitals, physician practices, labs, immunization registries, cancer registries, and more. The good thing is that many workflows and requirements are standard (or near-standard) across sites. The bad thing is that data structure and data content will vary.
How do you know you’re hitting your requirements? Testing and validation. Most HIEs do this. The problem is, small changes to an interface can take a long time to test and validate. For instance, a 15-minute coding change can take 2 weeks to validate.

The best way to reduce time spent on testing and validation is to automate the process. So that 2-week test cycle can be reduced to 1 hour.

And that’s exactly what smart HIE leaders are doing: they are finding ways to automate testing. This ensures that interfaces are delivered faster – and with more quality and confidence.

Caristix and HIE interface testing

The Caristix platform automates testing and validation for interfaces. Check out our tutorials for common validation scenarios.

Watch the on-demand demo of the Caristix Workgroup platform. You won’t be disappointed.

Interfacing Capabilities and Costs

When you first start researching the interfacing capabilities of each engine vendor, you might be overwhelmed. If you’re in a startup, small company, or a hospital with fewer than 100 beds, get ready for sticker shock. Interfacing and integration don’t come cheap.

And if you’re in a bigger organization and you need a new engine, get ready for complexity and value propositions that may be overkill.

healthcare interoperability maturity curve

 This post will help you match your needs to the capabilities in the market. And we’ll look at the hidden costs beyond the engine technology.   

Point to point

If you’re just getting started with interfacing, you’ll want to consider simple point-to-point connections. These are interfaces that are custom-built between two systems, and they don’t go through an engine. The advantage? You can get up and running quickly. But this technique is hard to scale beyond a handful of systems, since every connection requires its own interface. Also, watch for HIT vendor costs. One thing that suprises teams that are new to interfacing is that many EMR and HIT vendors charge for access. Even if you build your own interface, they will charge a licensing fee for 3rd party access to the data in their systems. And if you rely on these vendors to change or add new interfaces, the cost rises quickly.

Interfacing capabilities

Once your needs expand beyond a handful of interfaces, you’ll look for an interface engine. While the complexity of coding varies from one engine to another, expect a learning curve and expect to invest time to get up to speed.

On the other hand, you’ll find that engines make it easier to handle changes from one transport protocol to another – for instance, blending TCP/IP and web services. And you’ll find that per-interface costs can drop, since you’ll reduce your dependency on EMR and HIT vendors for changes to their message formats.

Integration, workflow management, and analytics

To meet the growing needs of IDNs and HIEs, many engine vendors now offer greater integration and workflow management capabilities. So for instance, you’ll find workflow management features that allow an interface to change as clinical workflows shift.

Another capability? Data analytics. Over the past 18 to 24 months, some vendors have been promoting their ability to work directly with the data flowing through the engine. You can query clinical and operational data directly to improve processes, decision-making, and care. This is powerful. But where you may run into issues is in the infrastructure. Just be aware that your infrastructure may need expensive upgrades in order to use these capabilities.

The real costs

Now that we’ve looked at the capabilities, let’s turn to the costs. Sure, you’ll invest in licensing and infrastructure – software and hardware. But your biggest line item will be the development costs.

What are the hidden development costs?

First, some interfaces are just more complex than others. For instance, a lab order interface may take twice as long to create as a registration or scheduling interface. But overall, interface development costs fit a pattern, which breaks down as follows.

Research and specification development

  • Reviewing product specs, developing a documentation template for project communications and populating it.

Gap analysis, mapping tables

  • Reviewing codes in both systems. Understanding differences in code sets. Creating mapping tables.

Interface build or coding

  • Actually writing the interface in the engine or coding by hand.

Unit testing

  • Testing each piece as you build the interface. This iterative process can take 10% of your coding time.

Integration testing

  • Testing clinical or operational workflows that the interface enables, in the test environment, before go-live.

Script development

  • Are there scripts that have to be developed for your interface to work? Expect development time and costs if this is the case.


Communications costs

  • A hidden cost that can escalate, especially if you don’t have a collaboration platform to keep track of versioning.

Post go-live support

  • The more applications you have, the higher the costs will be.

Reducing development costs

You can reduce your development costs by incorporating interface lifecycle management into your technology stack. Interface lifecycle management software can reduce the time and cost of research and specification development, gap analysis, testing, and more. As your requirements become more complex, the more you’ll bring your costs down with interface lifecycle management best practices and software.

Check out Caristix Workgroup for a full interface lifecycle management suite  (16-minute on-demand demo available).

What are HL7 requirements?

Requirements Thinkinginterfacing-project-assets

What are HL7 requirements? First, in the world of software engineering, requirements refer to documented needs that an application or system must perform. Requirements are critical for both designing the software and verifying that it works.
In the world of HL7 interfacing, requirements thinking is the right way to build an interface. The problem is, traditional HL7 requirements-gathering leaves serious gaps.

Traditional HL7 Requirements Approach

  • Key technique: manual analysis and pipe counting in message samples
  • Small data samples
  • Incomplete and/or outdated documentation

The result is a series of low-fidelity, low-trust requirements that raise more questions than they can answer easily:

“What exactly is connected here?  Which messages, and which data structures?”

“What is optional in which workflow?”

“Which data sets are applicable?”

“Is the meaning the same in both systems?”

And this means analysts and developers end up with a best-guess interface and fix issues as they pop up. They enter a trial and error cycle.

Traditional Trial and Error Pain

The pain around trial and error extends beyond analysts and developers. Slowdowns impact everyone who is dependent on smooth information exchange within the healthcare organization. Without good requirements, it becomes impossible to accurately forecast integration project effort, timelines, and (worst of all), costs. Similarly, you can’t assess risk accurately. Go-lives become a nightmare, since that interface will continue to be tweaked once the new systems are in production.

Recommendation: Better HL7 Requirements

When we work with our clients and their integration teams, we recommend they generate 3 key requirements documents at the start of a project:

System specifications

Create a system specification (for each system in the interface), or what we call a profile. This will give you a run-down of the data and messages that an interface sends and/or receives. One way to create a profile or spec from your system data is reverse-engineering. Read about reverse-engineering and why you might want to consider this technology for your next integration project.

Gap analysis

Also create a gap analysis – a list of all the differences between the two systems you’ll be interfacing. In essence, a good gap analysis will give a series of mapping tables – which data elements need to be mapped, transformed, or somehow communicated or manipulated from one system to the other. Read more about gap analysis.


Finally, you’ll want to document your clinical workflows. Your interface will need to support your clinical and administrative processes, which are mirrored by how the messages flow. Does an ED admit work differently than a med-surg admit? Make sure you capture that; the interface must handle both workflows. If a patient is transferred, does the LIS need to know? If so, capture that. Workflows impact your interface configuration – and they affect your test plan. Read more about workflows and why you need to map them.

How Caristix Software Handles HL7 Requirements

When you create requirements documents, you need a way to track them and update them. Check out the Caristix Workgroup on-demand demo to see how Caristix technology solves this problem.