In Version 24.02 of OIC, we have changed the way in which OIC transports and processes HL7 messages in the OIC runtime. These changes have been made to improve performance and to provide a future-proof solution for features that we intend to add at a later date. I can’t provide too many details on those features in this blog post, but if you follow these instructions for building integrations that process HL7 messages, adopting those future features will be much easier.  

These changes apply to users who have already joined the early adopter program and built integrations using the MLLP adapter and the new Healthcare Action from the developer palette. If you have not already used the new OIC healthcare features that were released in 23.10, then you should start with this blog post to understand how to use the new features. The demo package referred to in that post already has the updated integrations that reflect the changes being discussed here. In any case, if you are planning on using OIC to process HL7 messages, you will find the following information useful.

OK, let’s get into the details. The changes required are reasonably simple. There are two main changes that you need to make:

1. Healthcare Message Reference

The packaging of the raw HL7 message received from the MLLP adapter and the way you must handle that message in your integration have both changed.

  • The message that you receive from an MLLP adapter trigger connection is now a Healthare Message Reference. You can take this reference and pass it directly into the Healthcare Action. You no longer need to decode using decodeBase64.
  • Likewise, when you send an HL7 message outbound from OIC, the Healthcare Action will produce a Healthcare Message Reference for you to pass directly into the MLLP adapter invoke connection. There is no need to encode to base64 first.

HC message map

 

2. Child Integration Interface

In the demo package introduced here, we use a routing pattern that forwards the incoming message to a child integration from the main handler integration for processing. We refer to the integrations as handlers and processors where you write a handler integration to deal with all incoming HL7 messages for a given TCP/IP connection. You can write many processor integrations to process each specific type of HL7 message. We have standardized on a common interface payload for the handoff from the handler integration to the child processor integration. This JSON document forms the interface or contract between the handler and the processor.

You don’t need to use this JSON message in your child integrations if you don’t want to. However, if you do, you will future-proof yourself to take advantage of features we have planned for the future. The idea is that if you use this JSON message as the contract in your child integrations now, you will not need to change anything in the future when we add features such as automatic routing, data based routing, and the ability to define custom routing rules. If we offer these features in the future, you will not need to write the handler integration. OIC will automatically route the incoming HL7 message to the appropriate processor integration based on your routing rules. For this to work, you need to build your integration using this JSON payload.

{
    "document-standard": "HL7V2",
    "document-version": "2.3.1",
    "document-type": "ADT_A01",
    "document-definition": "HL7V2_ADT_A01",
    "message": [
        {
            "healthcare-message-reference": "clm:base64_meta.base64_payload1",
            "message-tracking-id": "123"
        },
        {
            "healthcare-message-reference": "clm:base64_meta.base64_payload2",
            "message-tracking-id": "abc"
        }
    ]
}

This payload provides metadata about the message and the capability to support batch messages as well. You can map this data using the data returned from the Healthcare Action when you call the operation Match and translate inbound message. An example of this mapping is shown below.

Processor integration mapping