This page describes how to set up and use the HL7 Inbound device. To insert the device, click Add/Edit Channel. From the drop-down, choose HL7 > HL7 Inbound Device. This device is responsible for bringing messages into the channel for processing by other devices.

Select the device to see the setup and configuration options.

Connection

The Connection tab contains options to control the connection between Connexion and the message server, as well as limits for message size and error behavior.

The tab contains the following:

• Network ports: the network ports where Connexion should "listen" for incoming messages. If Connexion should listen to multiple ports, list them on individual lines. Network ports can be listened to across all devices (the default) or on a specific device. If the port should be listened to on a specific device, select the radio button and specify the IP address of the device.
• Advanced TCP Options: use these options to set advanced behavior for the TCP connection. Choices include:
  • KeepAlive: Choose this to use KeepAlive messages. These messages are sent to verify that the link between the HL7 Inbound Device and the source HL7 message system is still operating.
  • NoDelay: Choose this option to disable the Nagle algorithm. This means that messages will be sent immediately, instead of being held until a transmission is of a certain size. This potentially improves system performance.
  • DontLinger: Select this option to close the socket gracefully without lingering.
  • Enable IPv6 Address: select the option to enable the use of IP v6 addresses.
• Connection Timeout (minutes): If no messages have been received for the specified number of minutes, sever the connection. If this value is zero (0), the connection will never time out.
• Max Message Size (KB): the maximum message size, in kilobytes, that will be accepted.
• Error Behavior: This option specifies how Connection should respond in case of an error. Choose ACK to send an acknowledgement using the specified error code. Choose Disconnect to abort the TCP connection immediately.
• Error Code (MSA-1): When an error occurs, and the Error Behavior is set to ACK, this is the code that is set in MSA-1 to indicate the type of error. Common values are:
  • AA: No error (don't tell the sending system about the error, even if the Error Behavior is ACK).
  • AE: Application error.
  • AR: Application reject.
• Number of Connections: the number of connections that should be accepted. Choices include:
  • Multiple: Accept multiple connections from any source (if the Accepted Host List is empty) or a specific source (if the Accepted Host List is populated)
  • Single: Accept a single connection. An error is generated for each connection after the first.
  • Single (don't listen): Accept a single connection. Do not listen for new connections if there is an active connection.
  • Single (close existing): Accept a single connection. Close the existing connection ONLY if the new connection has the same IP address.
• Accepted Host List: A comma-delimited list of IP addresses that are allowed to establish connections with the device.
• Error Rule: Send messages to the Error queue if this condition is met.
• Filter Rule: Send messages to the Filtered queue if this condition is met.

Options

The Options tab allows you to control the encoding, continuation type, and logging behavior for incoming HL7 messages.

The following are available:

• Encoding options:
  • Encoding: Choose the type of encoding the incoming HL7 messages will use. The default is Western European (ISO).
  • Start of Message Character: This is the character/string that indicates the start of an HL7 message.
  • End of Message Character: This is the character/string that indicates the end of an HL7 message.
• Continuation messages: Some legacy systems, for example, mainframes, have limits on message size. HL7 provides logic for "stitching" messages together into a single, distinct message in Connexion. There are three options available:
  • None: Do not combine messages.
  • Strict mode: Messages are combined according to the accepted HL7 specification.
  • Interpretive mode: Does not require adherence to the HL7 specification, but segments are only inserted if the segment type and set id are unique.
• Ack/Logging
  • Store Ack (HL7 ACK): controls whether to store the ACK messages, generated on errors.
  • Debug logging: Choose what type of logging you want Connexion to perform
    • None: No logging is done.
    • Debug: Only debug level logging (errors and warnings) is performed.
    • Full: Logging for all events in Connexion is performed (errors, warnings, and informational messages).

SSL encryption

You can run the device using SSL encryption. Go to the SSL Encryption tab to configure.

Click Enable SSL Authentication & Encryption. If someone has provided the certificate, you can paste it into the Certificate field. You can also generate a self-signed certificate from Connexion by clicking the Generate Self-Signed Certificate button. Doing so will populate the Certificate field with the required certificate information.

String replacements

The String Replacements tab allows you to search the incoming HL7 message for text and replace it with other text before it is passed to the next device in the channel (usually the queue). This transformation is useful especially when Connexion receives messages that cannot be parsed if, for example, the message contains four-character segments. Use the String replacements to add text to make the message parse-able.

Double-click in the String to Replace column to activate the field and enter the string you want to replace. Double-click in the Replacement String field to activate the field and enter the string you want to use as a replacement.

If you want to use regular expressions for the string replacement, check the Use Regex box.

ACK Transform

A message is sent for every HL7 message processed by the HL7 Inbound Device, either success (ACK) or failure (NACK). You can use ACK Transforms to create custom ACK conditions and messages. For example, you might always want to reject messages that meet certain criteria, even though they are properly formatting HL7 messages.

The same filters are available through the ACK Transform as the HL7 Transform device.