Overview Decisions HL7

Understanding an Interface

An interface in Decisions is comprised of three essential parts:

1. Receivers – Get HL7 messages from a source.  (TCP / IP, Files, Databases, etc.)

2. Processing – Applying rules, data transformations, assigning tasks and workflows using the data that was sent to Decisions.

3. Emitters – Sending HL7 messages back out to another system that is waiting to receive those messages.

Receivers

There are 3 types of message receivers in Decisions:

1. TCP/IP
2. File System
3. A Flow

NOTE: A flow in Decisions can use any of the hundreds of flow steps and the external system integration capability to get data.  This means that option 3 can receive an HL7 message from hundreds of different types of sources like: databases, social networks, web services, email, phone calls, and more. 

Processing

With every interface you create you automatically get a designer project where you can build workflows and rules.  These workflows allow you to process the message and make use of the data within the message.  This is where all of the intelligence you want to apply to your HL7 data stream is applied.

Emitters

Emitters are the exact opposite of receivers and send messages out to other systems.  There are 3 types of emitters:

1. TCP/IP
2. File System
3. Another Decisions HL7 Interface

NOTE: There is no ‘flow’ emitter like you have a flow receiver.  This is because you can simply do anything you like with the message in the main processing flow and that may conclude your work with the message.

Creating your First Interface

To create your first interface you simply browse to the HL7 Interfaces folder in your Decisions installation and click the Add HL7 Interface button.

When you click Add HL7 Interface you will get a dialog that looks like next Figure – New Interface Dialog.  This dialog has the following properties:

1. Name – This is the name of your HL7 Interface.
2. Description – This is a free text description that can help you or others in your organization understand what the purpose of a specific interface is.
3. 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. You will see these messages in your dashboard and you will be able to make changes to them to allow them to process.  Examples of reasons that the strict parser would discard a message:
   1. Segments or data that are required but missing
   2. Segments that are out of order
   3. Segments that have too much data
   4. Malformed data (like dates)

4. Only Allow Specific Message Types – Enabling this setting gives you a list of all acceptable message types and allows you to specify message types that this interface will process. All other message types will be ‘logged’ but ignored.

5. 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.  (This limitation is due to our post processing flow described below.)

6. Enabled – This setting turns on all receivers and emitters that exist as a part of this interface.

Once you hit ‘OK’ and your new interface is created you will immediately see it show up in the dashboard.  If you set your interface to be enabled it will be colored green, otherwise it will be red. 

To start setting up the details of your interface, simply click on it in the dashboard or use the folder tree on the left to select your new interface.

Setting up Receivers

Once you’ve defined your interface you’ll want to start setting up receivers so that your interface can act on messages sent to the HL7 Mediator by other systems.  From your interface dashboard you should see a button called Add Receivers.

Clicking this button gives you a list of receiver types.

File Receiver

The file receiver gets messages from a disk drive and starts the processing of the message. 

The properties for a file receiver are:

1. 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. 

2. 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.

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

4. 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

5. 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.

6. 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. 

7. 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.

1. Daily –
2. First Day of Month –
3. Last Day of Month –
4. Monthly –
5. 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. 
6. *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.
7. Weekly –
8. Yearly

Once you’ve created a receiver you should see it on the interface dashboard as shown next.

 

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.  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.

Flow Receiver

The most flexible receiver of all is the flow receiver.  The flow receiver can do anything that the Decisions workflow engine can do.

Dealing with Receiving Messages

Once you have enabled receivers you should be able to start receiving messages.  You will be able to see these messages showing up on the interface dashboard as in Figure.

 

If you right click one of the messages in the recent list you will get an action that allows you to view the message.  In the next Figure – Received Message you can see the receiver (or message source) for this message.  In the tree you can view the whole HL7 message structure, and on the right hand side you have the ability to edit the message. 

There is an indicator on the bottom of this window which will tell you if the parser encountered any errors during the processing of this particular message.

Processing Messages

In your interface there are 3 distinct views:

1. Interface Dashboard – a view of the most important data related to your messages being processed on this interface.

2. Designer View – a Decisions designer project where you can build flows, forms, rules, and reports related to this interface.

3. Folder View – an administrative view of all of the data in this interface. An interface is really a ‘folder’ of data elements and can have messages, tasks, and more.

To define how this interface processes and deals with HL7 messages you need to switch to the Designer View shown in the next Figure – Designer View of Interface.

 

In this view you can see 3 workflows that are automatically created for you.  These three workflows have three different jobs:

1. Pre-Processing Flow
2. Processing Flow
3. Post Processing Flow

Important Note: All HL7 Interface flows expect a message envelope which contains multiple HL7 messages.

Pre Processing Flow

This flow gets the HL7 message as text before the message is parsed into an actual HL7 object.  The purpose of this flow is to allow you to perform manipulations on the message that may be required to make the message process successfully. 

If you have a system that sends nonstandard or malformed data, but does this consistently or according to some rules you can make changes to the messages before the main processing happens within the Decisions platform. 

Because this flow works with the text of the message you can use any of the standard text and rule steps available in Decisions.  We also provide a number of flow steps specific for helping deal with HL7 text that is in the ER7 format (broken up by pipe characters typically).

1. Add Segment At Position

Inserts the specified text (assumed to be a segment) at a position in a String[] of segments. 

Example:

PID|1|Some Value|Some Value

PV2|1|Some Value|Some Value

Add Segment (PV1|1|Some Value) at position 2 would yield:

PID|1|Some Value|Some Value

PV1|1|Some Value

PV2|1|Some Value|Some Value

2. Clean Special Chars Before Segment Start

HL7 relies on newline and carriage return characters that sometimes cause problems.  You can use this step to remove these special characters.

3. For Each Segment Array in Envelope

This takes the main text of the whole HL7 message which is assumed to be a list of messages and gives you each individual message as a String[] of segments one at a time.

4. Get Data From Segment By Position

Gets data from a specific segment by the position of the data in the segment. 

For Example: PID|1|First Value|Second Value

The PID segment, position 2 is the text “First Value”

5. Get First Segment By Type

Returns a segment from the array of segments by segment type name.

6. Get Segment Position

Gets the position or index of a specific segment.

7. Get Segments By Type

Gets all segments of a specific type as a String[]

8. Join Messages Into Envelope

Takes a String[] and converts it into a string with “message separator” characters in between each message.

9. Join Segments Into Message

Takes a String[] and converts it into an HL7 message with “segment separator” characters in between each segment.

10. Remove All Segments By Type

Removes all the segments with a matching type name.

11. Replace Data In Segment By Position

Substitutes new data in a segment by the position value.

12. Split Envelope Into Messages

Splits an envelope (string) into a String[] by the message separator character.

13. Split Message Into Segments

Splits a message into a String[] of segments by the segment separator character.

Processing Flow

The processing flow is where the Decisions HL7 engine provides the most value.  By default this flow is setup to do no work, so out of the box you can simply use the Decisions HL7 Mediator to receive messages from systems and send them right back out again unmodified.  This can be very useful to create a single hub where messages are distributed to a wide range of systems in your environment, but the processing flow lets you inject behavior. 

There is not enough that can be said about the importance of this part of the HL7 Mediator.  This processing flow allows you to the following very simple examples:

1. Stop the message and assign tasks to people (alerts, corrections, notifications)
2. Transform the message using databases, web services, math, text manipulation and more
3. Store the messages in other systems
4. Transform the message data
5. Have people manually correct the message data
6. Compare the message data to other systems and allow it or discard it
7. Merge messages with other messages

Input to the Processing Flow

The processing flow takes an HL7 Message Envelope as input.  This envelope may have multiple HL7 messages in it. 

Output of the Processing Flow

The flow outputs the same HL7 Message Envelope with messages changed, removed, or added so that the interface can send these messages along to other systems via the configured emitters.

Workflow Steps

The processing flow also has a special set of HL7 message specific steps that can be used in the workflow engine.  Most of these steps will have an obvious use to someone familiar with HL7 messages and syntax, however; A few of these steps require explanation because they are particularly useful. 

1. For Each Abstract Message in Envelope

This step iterates through all of the HL7 messages in the envelope and allows you to work with one message at a time until your work is complete.  This is commonly used with the Cast Message as Another Message Type step which lets you treat a message as another type. 

2. For Each Message in Envelope

This step is similar to the one above except that you specify the message types you expect to be processing and you get separate paths for each message type to modify this message in the workflow.

       3. Send to Interface

This step allows you to send a message directly to an interface at a specific ‘stage’ of the processing. 

          Pre Processing

          Processing

          Post Processing

          Emitter

Post Processing

The post processing flow behaves as the counterpart to the preprocessing flow.  It takes the raw HL7 text that the processing flow has passed through and allows it to be modified before it is sent over to receiving systems via the emitters.  This allows you, once again, to accommodate systems and services that do not support the standards appropriately.

 

Emitters

Once you Received and Processed the messages, you’ll want to send them out using Emitters. To create an Emitter you should use Add Emitters button on your Interface Dashboard.

 

 

File Emitter

The file emitter sends messages to a disk drive. 

The properties for a file receiver are:

 

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.

4. 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 as shown in next Figure – Interface Dashboard with Emitter.

 

 

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:

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:

 

 

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.

 

Additional Resources

• Integrating Decisions with External Oracle Database