Custom Message Handlers

 Previous  Top  Next

ADVANCED FEATURE:

 

First implemented in Version 2.4 of the HL7 Listener is the ability to define a custom message handler ActiveX/Com object.  To configure the HL7 Listener to use a custom message handler check the box marked 'Implement a custom message handler' and then enter the ActiveX/Com objects [ObjectName.ClassName] in the text box provided.  Click the 'Test' button

 

 

What is a custom message handler?

 

A custom message handler allows you to create (or have created for you) a custom ActiveX/COM process that will be called from the EasyHL7 listener.  With your custom message handler you can override the default behavior of the Listener service.  This can be useful if you need to:

 

1. Respond in 'real-time' to a sender.  An example of when you might need to do this is if your solution needs to respond to real-time QRY messages with the HL7 event 'Q01'.
2. Integrate your own message handling directly into the EasyHL7 listener. I.E. you do not want to have a separate process that polls the output folder of the listener service and processes HL7 messages.
3. Send 'non-standard HL7' acknowledgements to the sender.  By default (and if configured to do so) the HL7 Listener service will send standard HL7 acknowledgements back to the sender.

 

To understand how to implement custom message handlers it is necessary to recap how the HL7 Listener works without a custom message handler in place.  When operating without a custom message handler HL7 data flows like so:

 

example 1

When operating with a custom message handler the HL7 message data flows like so:

 

 

example 2

example 2

 

The COM Interface

 

It's not within the scope of this document to discuss "HOW TO" write and design ActiveX/COM objects.  That's why this feature is an 'advanced' feature.  If you are not a programmer, this section will probably not make sense to you.

 

When designing your custom message handler it MUST have the following interface:

 

•It must be an ActiveX/COM object.  This means that the object must able to be created using the CreateObject() method implemented in MS VB and MS VB.Net.

 

It must contain the following Public Read/Write Properties:

 

•IsError - Boolean  (0 = false, -1 = True)
•LastError - VB String (BSTR for C#,C++ Programmers)
•SaveMessage - Boolean (0 = false, -1 = True)

 

It must contain the following Public Methods:

 

•ClearErrors() - No Parameters, no return value.  When called, it should set the IsError property to 0 and the LastError Property to ""
•ProcessMessage(strMsg, strMsgType, strMsgEvent, strACK) - This is the main processing method and the heart of the custom message handler.  It must return a VB String (BSTR for C#,C++ Programmers).  The parameters are:

 

1. strMsg - VB String (BSTR for C#,C++ Programmers).  Will contain the entire HL7 message received by the listener service.
2. strMsgType - VB String (BSTR for C#,C++ Programmers).  Will contain the HL7 message type (ADT, SIU, QRY etc).
3. strMsgEvent - VB String (BSTR for C#,C++ Programmers).  Will contain the HL7 message event (A08, S14 etc).
4. strACK - VB String (BSTR for C#,C++ Programmers).  Will contain the HL7 Acknowledgement that the listener service intends to send back to the sender, or an empty string ("") if the listener service does not intend to send an acknowledgement back (see the configuration options).

 

Design/Programming Notes:

 

The listener service will instantiate (create) the custom message handler when the service starts.  If an error occurs (i.e. the object cannot be created because it's not registered properly OR the object is created but the IsError property returns True (-1) immediately after creation) the service will immediately shut down.

 

Whenever the service receives an HL7 message it will do the following:

1. Call the ClearErrors() method of the object.
2. Call the ProcessMessage() method, passing it the 4 parameters described above and saving the return value.
3. Check the IsError property of the object.  If it is True (-1), the listener will immediately send a NACK (standard HL7 negative acknowledgement) back to the sender and the HL7 message will NOT be written to disk.  Also the value of the LastError property will be written to the listener service log file.  If the IsError property is False (0) it will continue with step 4.
4. If the call to ProcessMessage() returned any value other than an empty string (""), this will be sent back to the Sender of the message as an acknowledgement.  Note that this will override any of the basic listener configuration settings.  Even if the listener is configured to NEVER send an acknowledgement, if you return a value from the ProcessMessage() method it will be sent back to the sender.
5. The last thing the listener service will do is check the SaveMessage property of the object.  If it is True (-1) the listener service will write the HL7 message to disk in the standard way.  If it is False (0) the HL7 message is discarded.

 

A simple scenario:

 

In your HL7 Solution you need ADT message types (patient demographic messages) to be written to the folder as normal, but you need SIU message types (appointment/schedule update messages) to be stored in a database and processed immediately and send back NO ACKNOWLEDGEMENT.  You do not need to create any custom acknowledgements, so you just want the listener to send an acknowledgement back to the sender as normal.

 

Your code could look like this (VB6 Notation)

 

Public Function ProcessMessage(strMsg, strMsgType, strMsgEvent, strACK) As String

Select Case Ucase(strMsgType)

Case "SIU"

LoadMessage strMsg

'We saved it in a database so we don't need the listener

'to write the message out to the folder

SaveMessage = False

'For SIU messages we want to make sure the Listener does not send an acknowledgement

ProcessMessage = ""

Exit Function

Case Else

'We want the listener to write the message out to disk

SaveMessage = True

'We want the listener to send back the normal acknowledgement

'(as configured)

ProcessMessage = strACK

End Select

End Function

 

Private Function LoadMessageToDataBase(strMsg)

'------------

'Code in here to save the message to the database     

'------------

End Function

 

 

EXAMPLE CODE TEMPLATES:

 

HermeTech provides some example templates for writing custom message handler DLLs.  They can be downloaded at the following URL:

 

     For MS Visual Basic 6 and VB.Net:

http://www.hermetechnz.com/EasyHL7/Examples

 

 

All of the examples use the HermeTech EasyHL7 ActiveX toolbox (it is not required that you do this) which you can download at www.hermetechnz.com

 

 

 


EasyHL7 Home Page