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.