HL7 Modules: Setting up Receivers & Emitters

Last Updated: 11/09/2018 Introduced in Version:

In Decisions, an HL7 Interface is a set of processing instructions, or flows, that determine what is done with a message when it is received and how it is transformed before it is sent to another system.  The most common ways that HL7 systems communicate are using TCP/IP-based interfaces, using the file system to hand off messages, and using a database.  Decisions support all of these types of “endpoints” or message communication mechanisms and much more using the flow engine.

Create Your First Interface

Start in the designer Folders and navigate to the HL7 Interfaces folder.  Right click and Select Add HL7 Interface or locate the Add HL7 Interface action at the bottom of the designer page (Figure 1). 

Figure 1

 

Add HL7 Interface

Set the HL7 Interface properties and settings, view the below list of HL7 Interface settings and its description. 

  • Name – This is the name of your HL7 Interface.
  • Description – This is a free text description box that can help you or others in your organization understand what the purpose of a specific interface is.
  • Strict Parsing Mode – Turning this setting on means that messages that do not confirm to the HL7 standard will not be sent to the processing flows. These messages will appear in the HL7 folder displayed on the dashboard, changes can be made on them to allow them to process.  Examples of reasons that the strict parser would discard a message:
    • Segments or data that are required but missing
    • Segments that are out of order
    • Segments that have too much data
    • Malformed data (like dates) 
  • Only Allow Specific Message Types – Enabling this setting gives a list of all acceptable message types and allows specific message types that this interface will process. All other message types will be ‘logged’ but ignored. 
  • Output Version – An interface can only send out messages as one version. If you need to upgrade or downgrade messages to different versions and send to multiple systems you can easily do this by using the HL7 Interface emitter to send messages to another interface that uses a different version. 
  • Enabled – This setting turns on all receivers and emitters that exist as a part of this interface. If you set your interface to be enabled it will be colored green, otherwise, it will be red.

 

Start setting up the details of the HL7 Interface.  Select from the blue action panel or right click on the Interface folder and choose Add HL7 Interface (Figure 2). 

Figure 2

 

Setting Up Receivers

After an Interface has been created to begin setting up a receiver. Select the new Interface to view the Interface dashboard. Navigate the Add Receivers action located on the top left of the dashboard and select from the list of Receivers Types (Figure 3).

Figure 3

 

Receiver Types

1. File Receiver: The file receiver gets messages from a disk drive and starts the processing of the message (Figure 4).

The properties for a File Receiver are:

  • Name – The name of your receiver. It is important to name receivers well if you plan to have many sources of messages for this interface. 
  • Description – a free text description to help you and others who maintain this interface understand the purpose of this receiver. This is a great place to provide details about the message source or contact information for that message source.
  • Enabled – You can enable and disable individual receivers by changing this setting.
  • Folder to monitor – the most important setting on a file receiver is the actual file system folder from which this receiver will draw messages. This can be a full local path like C:\hl7 in\hospital1 or it can be a UNC path like \\HL7Server\AllMessages\Hospital1
  • Send ACK when processing complete – This tells the HL7 mediator to send an ACK message back to the other system when the message has been successfully parsed. Because the HL7 mediator can assign tasks to humans and do long-running workflow processes we do not wait for the message to be fully processed by the mediator before sending back an ACK message. 

                   **NOTE: If your requirements necessitate sending an ACK message to another system later in the process you can simply do this at the point you specify in your processing flow.

  • Archiving – These settings allow you to specify alternative folders where processed and errored versions of the messages can be stored. Even without these options the Decisions HL7 Mediator will track successful and unsuccessful messages in the database for reporting purposes. 
  • Calendar – The calendar allows you to specify how frequently this receiver will look for new messages at the specified location. There are many options for the calendar.  Most of these options speak for themselves, but a description is provided for a couple of them.  Timespan has an asterisk because it is the most commonly used option.
    • Daily –
    • First Day of Month –
    • Last Day of Month –
    • Monthly –
    • Specified Job – This allows you to set a specific date and time to run the interface. It will run at that one point in time and not again. 
    • *Timespan – This allows you to set an interval between checks from 1 second to 1 year. The receiver will start immediately and check whenever the interval has passed.
    • Weekly –
    • Yearly

Figure 4

 

The Receiver will appear on the right side of the Interface dashboard under Name (Figure 5).

Figure 5

 

2.TCP/IP Receiver: If the system sending you messages supports TCP/IP connections these can be configured as a TCP/IP receiver.  TCP/IP receivers get messages as soon as they are sent from the sending system so there is no need to configure a schedule (Figure 6). 

The properties of a TCP/IP Receiver are as follows:

  • Name – The name of your receiver. It is important to name receivers well if you plan to have many sources of messages for this interface.
  • Description – a free text description to help you and others who maintain this interface understand the purpose of this receiver. This is a great place to provide details about the message source or contact information for the maintainer of that message source.
  • Enabled – You can enable and disable individual receivers by changing this setting.
  • IP Address – The IP address on which this receiver should listen. (Leaving this setting blank allows the receiver to listen on any valid IP address for this server.)
  • Port – The port number for the socket on which this receiver should listen. This must be a valid port for the receiver to initialize and start receiving messages.
  • Override Standard Low-Level Message Indicators (Message Framing) – TCP/IP connections use special text characters to indicate when a message is complete. If you need to customize these you may do so by enabling this option
    • NOTE: The characters must be entered using ‘Hex’ notation for example 0x0B
  • Send ACK when processing complete – This tells the HL7 mediator to send an ACK message back to the other system when the message has been successfully parsed. Because the HL7 mediator can assign tasks to humans and do long-running workflow processes we do not wait for the message to be fully processed by the mediator before sending back an ACK message. 
    • NOTE: If your requirements necessitate sending an ACK message to another system later in the process you can simply do this at the point you specify in your processing flow.
  • Never Close Connection (nonstandard clients) – Some clients, like 7-Edit the popular HL7 editing application, require that the server maintain an open connection after it has first been established. If you find that your receiver gets a single message and then stops receiving you can try enabling this setting.
  • Use File System As a queue – If your HL7 interface cannot process messages as fast as they are being sent to the interface you can use the file system as a ‘queue’ to store messages so that you do not block the messages from getting sent over the TCP/IP connection.
  • Always Trim Standard Frame Chars – This setting tells the parsing engine to always be sure to strip any standard message framing characters (as described above) from the messages received.

Figure 6

3.Flow Reciever: The most flexible receiver of all is the flow receiver.  The flow receiver can do anything that the Decisions workflow engine can do (Figure 7).

  • Name– The name of your receiver. It is important to name receivers well if you plan to have many sources of messages for this interface. 
  • Description – a free text description to help you and others who maintain this interface understand the purpose of this receiver. This is a great place to provide details about the message source or contact information for the maintainer of that message source
  • Flow for Messages
  • Calendar – The calendar allows you to specify how frequently this receiver will look for new messages at the specified location. There are many options for the calendar.  Most of these options speak for themselves, but a description is provided for a couple of them.  Timespan has an asterisk because it is the most commonly used option.
    • Daily –
    • First Day of Month –
    • Last Day of Month –
    • Monthly –
    • Specified Job – This allows you to set a specific date and time to run the interface. It will run at that one point in time and not again. 
    • *Timespan – This allows you to set an interval between checks from 1 second to 1 year. The receiver will start immediately and check whenever the interval has passed.
    • Weekly –
    • Yearly
  • Requeue if job fails:
  • Create Task if job fails:
  • Run job on Startup:

Figure 7

 

Setting up Emitters

Once you Received and Processed the messages, a message can be sent out using Emitters.  Select Add Emitters on the blue action panel next to Add Receivers in the Interface dashboard.

Figure 8

 

File Emitter

The File Emitter sends messages to a disk drive. 

The properties for a File Emitter are:

Figure 9

 

  1. Name – The name of your emitter.
  2. Description – a free text description to help you and others who maintain this interface understand the purpose of this emitter.
  3. Enabled – You can enable and disable individual emitters by changing this setting.
  1. Destination Folder – the most important setting on a file emitter is the actual file system folder to which this emitter will send messages. This can be a full local path like C:\hl7 in\hospital1 or it can be a UNC path like \\HL7Server\AllMessages\Hospital1

Once you’ve created an emitter you should see it on the interface dashboard, called Interface Receivers and Emitters.

 

TCP/IP Emitter

If you would like to send messages to the system that supports TCP/IP connections these can be configured as a TCP/IP emitter. 

The properties of a TCP/IP emitter are as follows:

 

Figure 10

 

Name – The name of your emitter. 

Description – a free text description to help you and others who maintain this interface understand the purpose of this emitter. 

Enabled – You can enable and disable individual emitters by changing this setting.

IP Address – The IP address to which this emitter should talk to.

Port – The port number for the socket to which this emitter should talk to.  This must be a valid port for the emitter to initialize and start sending messages.

Override Standard Header and Footers (Hex Framing) – TCP/IP connections use special text characters to indicate when a message is complete.  If you need to customize these you may do so by enabling this option

NOTE: The characters must be entered using ‘Hex’ notation for example: 0x0B

 

Redirect to HL7 Interface

You can use this emitter to send messages to another HL7 Interface.

The properties of the Interface Emitters are as follows:

Figure 11

 

Name – The name of your emitter. 

Description – a free text description to help you and others who maintain this interface understand the purpose of this emitter. 

Enabled – You can enable and disable individual emitters by changing this setting.

HL7 Interface – You should pick an Existing HL7 Interface.

     NOTE: You are not allowed to pick Current Interface to send messages to.

 

Links

HL7 Module Overview

For more information on setting up HL7 see attached links.

Additional Resources