GenericHL7Output node
Use a GenericHL7Output node to prepare a message for the destination application.
It is recommended that the HL7DFDLOutput node is used for new and updated applications if possible, as the DFDL message model has the following benefits.
- DFDL is an open-standard format whereas MRM and the HL7v25P message set are proprietary to IBM Integration Bus.
- The DFDL editor provides simpler tools for developing and testing extensions to the HL7 schema compared to MRM and the HL7v25P message set.
- The DFDL message model supports HL7 versions 2.7, 2.6, 2.5.1 and earlier whereas MRM and the HL7v25P message set only support HL7 version 2.5.1 and earlier.
For more information about the HL7DFDLOutput node, see HL7DFDLOutput node.
Purpose
The GenericHL7Output node receives an HL7 message in the MRM domain and opens connections to a destination application that is listening on a TCP/IP port. When the connection is established, the HL7 message is sent with an end of record that is set to the Trailing MLLP bytes property delimiter, which has a default value of 1C0D. If the data was not sent successfully within the time limit that is specified by the Timeout sending data record (seconds) property for the node, the message is passed to the Failure terminal.
After successfully sending the message, the GenericHL7Output node waits for an acknowledgment (ACK) from the destination application. An HL7 acknowledgment is stripped of MLLP bytes, parsed, and the return code is checked. If an error occurs in the GenericHL7Output node, the message is passed either to the Log Retry terminal or the Failure terminal.
If delivery succeeds and an AR code is returned in the acknowledgment, and if the retry limit was not exceeded, the message is passed to the Log Retry terminal.
If the message is delivered and an AE code is returned in the acknowledgment, or if no valid acknowledgment is received, the message is passed to the Failure terminal.
If the message is not delivered, it is assumed that the destination is not available, and, if the retry limit was not exceeded, the message is passed to the Log Retry terminal.
If the Log Retry terminal is not connected, or if the path ends in success, delivery is retried. If the Log Retry terminal is connected and an exception is thrown downstream, the message is not retried and the message is passed to the Failure terminal.
If the Failure terminal is not connected, an exception is thrown.
For information about HL7, see Health Level Seven International.
The GenericHL7Output node is contained in the Healthcare drawer of the message flow node palette, and is represented in the IBM Integration Toolkit by the following icon:
Using this node in a message flow
An example of how to use the GenericHL7Output node is shown in the Healthcare: HL7 to HL7 built-in pattern in the Healthcare category in the Patterns Explorer view.
When a GenericHL7Output node is used in a message flow, the node expects to find a message in the MRM tree that has been parsed against the HL7 message in the HL7v25P message set. If you are not certain that messages passed to the GenericHL7Output node are correct, you can set the Validate property to force parsing before processing begins. If the message is successfully sent to the configured destination and an acknowledgment of successful processing is returned from the destination, the acknowledgment is passed to the Out terminal of the node.
If you want the node to try sending the message again after a failure, you must set the value of the Retry limit property to the number of times that you want the node to try to send the message. The node tries again every 10 seconds, but you can alter the interval by changing the Retry interval (seconds) property. If you also want to log every retry, you must select the Log retry property. When the Log retry property is selected, the message is passed to the Log Retry terminal for each attempt. The Environment holds the values that you can use in your log message, see the following Environment table.
If you wire the Log Retry terminal, the message flow thread ends in success and further retries are attempted. If uncaught exceptions are thrown on this thread, the retries do not continue.
If a message is passed to the Failure terminal, your message flow acts according to your error handling procedures. The Failure terminal must be connected so that the error is logged and the data is either saved, an exception is thrown, or both. If the Failure terminal is not connected, the error causes silent failure, no exception is thrown and no events are recorded in the event log. For error codes and other information that you can use in your error handling, see the following Error table.
If a failure occurred in the GenericHL7Output node, the message is passed to the Failure terminal. LocalEnvironment.HL7 contains the fields that are shown in the following Environment table. These fields give information that is used to build a negative acknowledgment (NACK) or create an error message.
Field | Description |
---|---|
FlowMilestoneReached | Indicates where the error occurred |
Retry | Indicates whether this action can be tried again |
ErrorCondition | Gives a textual description of the error |
Attempt | If the error occurs in a retry loop, this variable contains the following text: Attempt <i> of <n> |
RetryCount | Indicates the current retry |
RetryLimit | Indicates the number of retries allowed |
The following Error table indicates the error codes that can occur.
Error | Terminal | Retry | Code | Error Text |
---|---|---|---|---|
The node failed to parse the incoming message by using the HL7v25P message set and the HL7 message format. | Failure | No | BADHL7 MESSAGE | The incoming HL7 message cannot be parsed. |
The node failed to send the message to the configured destination. | Log Retry | Yes | SENDHL7 | TCP/IP error. The HL7 message was not sent. |
The node failed to parse the acknowledgment. | Failure | No | ACKPARSE ERROR | MSH error while ACK message was being parsed. |
The acknowledgment was received but no acknowledgment code is present. | Failure | No | ACKERROR | MSA parsing or validation error: MSA 1. The acknowledgment code is null. The ACK contained the following error message: error_message |
The acknowledgment was received but no message control ID is present. | Failure | No | ACKERROR | MSA parsing or validation error: MSA 2. The MessageControlID is null. The ACK sent the following error message: error_message |
No acknowledgment was received in the timeout period. | Failure | No | TIMEOUT | The node failed to receive ACK message within the specified time-out. |
The node failed to receive the acknowledgment. | Failure | No | RECEIVE ACK | TCPIP error. The node failed to receive ACK message. |
The node tried to deliver the message but the node reached the configured retry limit. | Failure | No | SENDHL7 TOOMANY REPEATS | The node failed to receive the ACK message. |
The node received AR acknowledgments but the node reached the configured retry limit. | Failure | No | ACKAR TOOMANY REPEATS | The node has retried sending the message and cannot successfully deliver the message. |
Configuring the GenericHL7Output node
After you add an instance of a GenericHL7Output node into a message flow, you can configure it
All mandatory properties for which you must enter a value (properties that do not have a default value defined) are marked with an asterisk.
Terminals and properties
Terminal | Description |
---|---|
In | The input terminal that accepts an HL7 message for the node to process. |
Failure | The output terminal to which the message is routed if the node fails to successfully send the message and fails to receive an acknowledgment of successful processing. |
Out | The output terminal to which the acknowledgment is routed if a message was successfully sent to the destination and an acknowledgment of successful processing is received. |
Log Retry | The output terminal to which the message is routed if the node either fails to successfully send the message or fails to receive an acknowledgment of successful processing and the retry count is not exceeded. |
The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the broker archive (BAR) file to deploy it).
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | GenericHL7Output | The name of the node. |
Short description | No | No | A brief description of the node. | |
Long description | No | No | Text that describes the purpose of the node in the message flow. |
Property | M | C | Default | Description |
---|---|---|---|---|
Connection details | Yes | Yes | localhost:2222 | The TCP/IP connection for the destination application in the form hostname:port |
Timeout sending data record (seconds) | Yes | Yes | 60 | The time in seconds that the node waits when it is attempting to send data or to receive an acknowledgment. |
Leading MLLP bytes | Yes | Yes | 0B | The leading MLLP byte, which is added to outgoing HL7 records and removed from incoming acknowledgments. |
Retry limit | Yes | Yes | 5 | The maximum number of times the node attempts to deliver an HL7 message to the destination application. |
Retry interval (seconds) | Yes | Yes | 10 | The interval, in seconds, between each attempt to deliver an HL7 message to the destination application. |
Log retry | Yes | Yes | Selected | Specifies whether each attempt to deliver a message is passed to the Log Retry terminal to allow logging. |
Property | M | C | Default | Description |
---|---|---|---|---|
Delimiter | No | No | Custom delimiter | This property is not editable. |
Trailing MLLP bytes | Yes | Yes | 1C0D | The trailing MLLP bytes that are used as an HL7 record delimiter. These trailing MLLP bytes are added by the TCPIPClientOutput node. |
Property | M | C | Default | Description |
---|---|---|---|---|
Delimiter | No | No | Custom delimiter | This property is not editable. |
Trailing MLLP bytes (Acknowledgment) | Yes | No | 1C0D | The HL7 delimiter that is used to detect the end of incoming acknowledgments. |
Property | M | C | Default | Description |
---|---|---|---|---|
Validate | No | Yes | None | This property determines the level of validation
of the incoming HL7 message
in the MRM domain. Valid values are:
|