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.
We’ve shipped our latest software to beta testers. And we’ve given the product a name: Caristix Reader. Like Adobe Reader, it’s free.
How to Change HL7 Segment and Field Definitions in Caristix Cloak
One of our Cloak customers is de-identifying close to 14 GB of clinical data coming from several healthcare information systems (including 2 ADTs and a lab system) at an IDN. This customer is asking some great questions that would help other Cloak users get more out of the software. Here’s an excerpt from our conversations.
The NK1 segment is giving me trouble. Specifically, field 5, the address. I created a sample message with this as the NK1.5 content:
123 EASY ST^Arlington^VA^22207The NK1 segment is listed as NK1.5.2 as being “other designation”, not the city, thus throwing off my address conversion. I have no means to identify subcomponent 2 as the city, I’m “stuck” with it being “other designation.”
It looks like the NK1 segment in the logs doesn’t follow the standard… (surprise, surprise;). In fact, based on the HL7 standard, the address would be stored in NK1.4 and city in NK1.4.3. It appears to be a naming issue within the data. You can modify the HL7 profile/specification that Cloak uses so the HL7 reference profile represents the data you’re working with (as opposed to trying to conform to the official HL7 specification). In other words, you can change the specification to remove the “other designation” field in the HL7 profile.
To do this, you would need either Caristix Conformance or Reader software. Reader is a free download available here.
Here’s the procedure:
1. Open Conformance or Reader.
2. Make a copy of “HL7 v2.6” profile in “New Folder”.
3. Rename the profile to something that make sense to you.
4. Browse to the NK1 segment and expand it.
5. Browse to NK1.5 and expand it.
6. Delete the “other designation” field.
7. Save the profile.
8. Go back to Cloak.
9. From the menu bar, go to Tools, Options, Reference Profile.
10. In the list of profiles, select the profile you just modified.
11. Click OK. The NK1.4.2 field name is now city.