Optional Listener Profile Settings
Contents
The Optional Listener Profile Settings are broken into 3 sections:
1.Section 6 - MSH Validation
2.Section 7 - Alternate ACKS and Idle Timeout
3.Section 8 - Listener Proxy Settings (Message Forwarding)
Section 6. (Optional) MSH Validation
With the UltraPort HL7 Listeners you can control which HL7 messages are accepted by your listener based on values in the MSH (Message Header) segment by checking 'Enable MSH Validation' in your primary profile settings. Checking the 'Save NAK Messages' box will cause the listener to save the HL7 messages which were sent a NAK in the HL7 data folder with a ".nak" file extension. If you do not check this box then the message will not be saved. After you check 'Evaluate MSH Segment for NAK' box you click the 'Edit MSH Validation' button to open the window shown below.
 Optional Listener Settings |
|
 MSH Validation Settings |
In this window you simply click on the MSH field you wish to validate and choose one of the options available. Then you can enter a custom Error Message which the listener will send back to the client in an HL7 NAK. Validation Options are:
•N/A (No Validation). There will be no validation done on this field. NOTE: When looking at this window fields which are highlighted in BLUE have some type of validation.
•Required. Simple validation. The field must NOT be blank.
•Required (In validation list). The field not only must contain a value but the value MUST be in the validation list (click the 'Edit' button to add/remove items).
•Required (Not in List). The field MUST contain a value (ie not blank) AND the value MUST NOT be in the validation list.
Further information. When an inbound HL7 message fails your validation instructions a NAK is sent back to the client and the message is discarded UNLESS you have checked the 'Save Nak Messages' button in your Primary Profile Settings. If you have chosen this option the failed message will be saved in the data folder with a .NAK file extension.
To view/edit a validation list click the 'Edit' button next to the validation list drop down list. Type your entries into the data entry space provided pressing 'Enter' after each entry. NOTE: The validation is NOT case sensitive (ie Labcorp and LABCORP are identical).
Editing a Validation List
Section 7. (Optional) Alternate ACKS and Idle Timeout
 Section 7 (Click to Zoom) |
New in version 5.0.4.
Alternative HL7 ACKS. By default whenever the UltraPort Listener receives a message that requires an acknowledgment it sends back a standard HL7 Acknowledgment of type AA (message was accepted). The listener can also send back a negative HL7 Acknowledgment of type AR (message was rejected) IF you are using the MSH Validation feature (see Section 7 below).
By checking the Use CA/CE instead of AA/AR in the HL7 Acknowledgments box in your listener profile you can instruct the UltraPort Listener to use the alternative positive acknowledgment type of CA (message was conditionally accepted) or CE (message was rejected due to error). As with the default settings the CE acknowledgment type will only be produced when you are using MSH Validation (see Section 7 below).
Use the Idle Timeout. In order to exchange HL7 messages securely over TCP/IP from a remote sender you have to implement a VPN. It can be tricky to configure a VPN properly to exchange HL7 messages over TCP/IP to a MLLP HL7 Listener (like the UltraPort Listener). If not configured properly the VPN can fail to recognize that a socket connection is no longer valid and will continue to try and deliver HL7 messages. This can result in the HL7 sender receiving errors when sending HL7 messages to the listener, even though the listener itself is actually working fine.
While the listener itself cannot really do anything about this issue, you may be able to mitigate the effects by using the Idle Timeout. If enabled the listener will periodically destroy and recreate itself if it has been idle (IE no HL7 messages received) for the designated period of time.
IMPORTANT: The Idle Timeout is only implemented in the UltraPort Listener Windows Services (NOT when running locally). And while this option is perfectly "safe" to implement we DO NOT recommend using it unless you have experienced connectivity problems similar to the ones described above.
Q: If it's "safe", why don't you recommend it. A: Because, if implemented, it will cause the listener to be "down" for up to 1 second while it resets itself. Example: You set the Idle Timeout to 10 minutes, and there are no HL7 messages received for 10 minutes. The listener resets itself and at EXACTLY that instant your Trading Partner decides to send you a message and they would receive an "Unable to Connect" error. We say that it's "safe" because ANY HL7 compliant HL7 sending software will recognize that error and attempt to resend the message. |
Section 8. Listener Proxy Settings (Message Forwarding)
In the optional settings tab you can configure your listener profile to act as a 'Proxy' for another application which uses the UltraPort Proxy Toolkit for Microsoft Visual Studio. For more information about the FREE UltraPort Listener Proxy Toolkit click here. The rule here is that if you're 'not sure' if you need to forward your messages to a Proxy Application then you probably don't.
Optional Listener Profile Settings (Message Forwarding)
In this tab check the 'Forward HL7 Messages' button to show the rest of the settings. Select whether the Proxy application is on the same computer as the listener or another. If it's another computer then enter the TCP/IP address for that computer. NOTE: If the proxy application is on another computer then the TCP/IP address must be on the same network as the listener computer. Enter the Interface Port Number (will be provided to you by the Proxy Application author). IMPORTANT NOTE: If the proxy application is on the same computer, then the interface port number MUST NOT conflict with any of the HL7 Port Numbers from any of your listener profiles OR (if enabled) the Global Monitor port number.
Two more interesting features in this tab. The 'Do NOT Save' checkbox. Your listener profile will use the Data Folder to 'queue' up messages to be sent to the Proxy Application. If the Proxy Application is stopped, not listening for messages, or even processes slower than the UltraPort Listener, the UltraPort listener will continue to receive messages and store them in the data folder with a (.pq) file extension. Finally the 'Test' button. You can click this button to manually 'Ping' the Proxy Application using the settings you've selected. It will tell you immediately wheter the settings are correct AND whether the Proxy Application is running and listening for messages. This is a built-in feature of the UltraPort Proxy Toolkit so the application authors don't have to do anything, it's automatic.
It is even possible to have multiple listener profiles sending HL7 messages to the SAME proxy application on the SAME port. This means that you can have multiple inbound TCP/IP HL7 data streams which all go to the same proxy application for final processing and distribution!
HL7+ Client Console Online Help - Click Here
HL7+ Management Console Online Help - Click Here