Macadamian Blog

A Guide to Working with HL7: Considerations and Recommendations

Geoffrey Parker

In developing healthcare software, there is a high chance that you will run into an integration challenge sooner or later and will need to understand HL7 messages.

Healthcare Tablet & Mobile App

In developing healthcare software, there is a high chance that you will run into an integration challenge sooner or later and will need to understand HL7 messages. HL7 is a standard for how healthcare information is packaged and communicated from one party to another. There are several versions of the standard and it does not define which fields are required. This has led to it being used differently by virtually every health entity on the planet.

Given that the standard does not define the required fields or how messages should be processed, the onus is on the software developer to understand how each source and destination being integrated has constructed their HL7 interface. This is key as it will influence how your application will be built or modified. Some of the differences can be hidden behind an abstraction layer. Others, such as how documents are digitally signed, will bubble all the way up to the UI layer.

Here are a few considerations to think about:

  1. How will a document be created?
    • Depending on how the system is configured, you might be issuing a create request, or it might happen automatically with an update if a prior copy of the data does not already exist.
  2. How will an event be changed or modified?
    • Is there an operation to undo the event that was incorrect, or do you need to send an update request and reference the original message?
  3. Some activities are implicit, others need to be acknowledged explicitly.
    • If a prescription is picked up, do you need to send an acknowledgement to other systems, or is there an assumption that happens implicitly?
  4. Who generates the message ID? How long do I need to keep it? And who needs the message ID in future?
    • For any request, you may need to send a follow up message using the original message ID. However, you would not know that in advance since it depends on the actions taken by the user of the software 5 or 10 minutes later.
  5. Can you get multiple records from a search or is the result binary?
    • When requesting results, will you receive a list of items that match the search criteria, or will it return no records if there is more than one result?
  6. How will the pagination of data work?
    • Do you provide an offset into the list of records, a reference to the last record received, or a page reference?
  7. Timeouts – what happens in the event of a timeout?
    • Is the activity impotent? Can you retry it safely, or do you need to verify the new state of the system?
  8. Consent override – in emergency situations, consent to access information could be overridden. How is that achieved?
    • Do you specify an “override” field in the request to override permission, or do you send a separate message to authorize an override for that user in advance of the permission request? Further, assuming you have sent the override, how long does it apply for? For one request, or for a block of time?
  9. Everything needs to be tracked and recorded in the audit log.
    • Any activity performed on the system, whether successful or not, needs to be recorded in the audit log.
  10. Dates, times and, time zones – what is the right time zone to use?
    • Does the system being communicated with expect dates to be presented in UTC, local state, or provincial times? Often the same information gets repeated in multiple places within a document but with subtle differences to the meaning.   The “location” might be repeated for where a medication is prescribed, dispensed, picked up, or receipted. In some instances, this will be consistent. For others, each event could be recorded differently. Furthermore, the details of what the location relates to are often not directly visible. It may be listed several parent nodes back in the document.
  11. Number formats change for different fields.
    • For the field that you’re specifying, how many decimal places does it require, and/or does it use scientific notation?

Working with HL7

Faced with all this, here are some suggestions for working with HL7 documents to maintain your sanity.

  • Plan ahead in the early stages of the project. Different locations have different requirements for accessing their systems. For example, depending on the user’s context, they may use a username or password, a USB dongle, or a random key generating fob.
  • Reduce the layers of abstraction. You’re going to need to refer back to the original document at some point. The more layers of abstraction you have between your code and the original document, the harder it is to work out what is happening.   Work directly in XML if possible.
  • Get sample messages from end points.
    • For output (and then migrate them to contain your data)
    • For input (so you know what you’re going to need to parse)
    • Get the schema definition if possible
  • Add more documentation to the HL7 message than what is required. It will help in debugging. Establish good relationships with someone on the end point. They will be instrumental in helping debug when things don’t work as expected.
  • Make sure you have a staging area. You will need somewhere to test solutions without messing up a live database.

With the Office of the National Coordinator (ONC) drafting a target for interoperability by 2017 and Meaningful Use Stage 3 promoting the use of APIs so that 3rd party vendors can create software that accesses your medical record, choosing a partner who understands HL7 and the challenges of integration has never been more important.

If you have any questions or perspective to add, I would love to hear from you.



Author Overview

Geoffrey Parker

Geoff is Macadamian’s Director of Healthcare Software Development specializing in healthcare software and is responsible for technical leadership, technology partnerships, and sales engineering. Geoff thrives on working with clients to identify and deliver the right solution for their individual needs. His career as a software professional has focused on delivering highly complex mobile and server side technology solutions. Geoff is happiest when pushing the technology envelope by doing things that haven't been done before. He has a Bachelor of Information Technology with Honours from the University of Queensland, Australia. When he’s not coding, you can find Geoff on the backpacking trails.