HL7 Sample Messages – Always the Best Way to Go

Despite previous warnings, I recently committed a cardinal interfacing sin when working on an HL7 integration project. Upon kicking off a large project involving several applications with which we’re interfacing, I requested both specifications and sample HL7 messages from the vendor. The specifications came right away; the sample messages unfortunately did not.

Rather than making a big deal out of the messages and insisting that we get them prior to interface construction, I dove right in to perform a gap analysis based on the specifications that we were furnished in order to determine the incompatibilities between the systems involved. After carefully identifying the mappings required to transform the HL7 messaging such that it would satisfy each system’s specs, the interfaces were configured.

It was time to test, and out came the disappointingly small (in some cases just 1 or 2 messages per application) sampling of test messages that had slowly trickled in but had been shelved until the ‘real’ work of building the interfaces could be completed. Those messages were loaded, the interfaces were turned on, and voila!


The sample data didn’t align with the specs, rendering my beautiful side-by-side comparison spreadsheets useless. The mapping tables I developed from those specs to translate representations of common fields such as gender, race, and relation? Worthless as well.

How could I have so quickly forgotten that the proof is almost always in the sample message pudding?

Specification documents are often hailed as the keys to unlocking the secrets of the import/export modules of healthcare applications and successfully brokering communication between disparate systems. Good specs do just that. The only problem is that you stand a better chance of finding a few needles in a hay mountain. They’re out there; they’re just not very plentiful.

The shortcomings of specs are attributable to a variety of factors:

  • They’re rarely updated at the pace of development. While correct at a particular moment in time, changes are often times made to the interface that either never make it into the document or do so after those changes have been introduced to the marketplace.
  • They’re often out of sync with upgraded software versions. Even if a vendor takes extreme care in updating both the interface and the specifications simultaneously, healthcare facilities may have upgraded their software since receiving their specification document and therefore unknowingly hand an outdated version to trading partners/interface analysts.
  • Variances in installed modules/features are difficult to document. Many applications offer a wide array of software modules and features that can be alternatively installed depending on the customer’s budgets or workflow that make the production of a “one size fits all” specification difficult.

But the messages don’t lie. Having them takes the guesswork out of determining exactly what is coming out of or readily received by a healthcare application. Today’s most sophisticated interface engines will even go so far as to take those messages and build an HL7 derivative to which they’ll conform at the click of a button! There’s not much left to the imagination, and thus interfaces can be built with a much greater level of confidence.

So if you’re a vendor, be sure to stamp out a good sampling (at least 50) of anonymous messages for each message type supported through your application interfaces each time a change to the interface is introduced. Doing so will not only be appreciated by interface analysts trying to connect your systems to others in a hospital, clinic, imaging center, etc. It will also ease your own interfacing burden by reducing the number of calls and questions you field related to interfacing.

And if you’re an interface analyst, stranded on a deserted integration island and given the choice between sample messages and specifications to ensure your survival, always opt for the messages. They represent much more than a means to validate interfaces – they can be vital to successfully building them. Just make sure you don’t settle for 1 or 2 like I did.

The following two tabs change content below.

Jason Williams

Jason Williams is a Sales Engineer focused primarily on the software vendor and medical device markets at Corepoint Health. Jason has over 10 years of software development and systems design experience.
  • http://www.break-line.net Max Drown

    Couldn’t agree more. Well put.

  • http://www.mwdn.com Eugene Shifrin

    Thank you for this post, Dave

    I suggest that you put link to it to first page of Neotool website.


    It is almost impossible to convince people to get samples, not specs.

    Thank you for this post, I already mailed it to 4 customers.