You create "Router Profiles" which contain instructions for how the router software sends your messages. A HL7 sender needs 2 primary pieces of information to send HL7 messages over TCP/IP. 1) The IP address of the HL7 server which is receiving the messages and 2) The HL7 Port Number that they are listening on.

 

You can create as many profiles as you wish but you can only "Enable" as many profiles as your product license permits (1 - Unlimited). While in "Demo" mode you can run the maximum.

 

NEW In version 5! You can test the TCP/IP Connection to the HL7 Listener from both the Router Profile Window AND the Monitor Tab of the Main Window! Just click the "Test the Connection to the HL7 Listener" button!

 

 

 

Primary Profile Settings

 

•Enabled. If this box is checked then when the program runs (either as a service or locally) a listener engine will be created for this profile.

•Profile Name. Enter a unique name for this listener up to 50 characters long.

•Profile ID. A short name (2-4 alpha-numeric characters) which is unique for each profile. The Profile ID is used when naming the traffic logs and archive files written to sub-folders in Data Folder so having a unique ID here assures not having the worry of duplicate file names being overwritten.

•Send TO Port Number. Enter the TCP/IP port number which this listener profile should send HL7 messages to. It must be a valid port number (1 - 64K).

•Target Listener Location. Where is the HL7 listener application that this profile is to send HL7 messages to? If you select 'A Remote IP Address' then you will need to enter the TCP/IP address for that computer. NEW! You can also select "A Remote DNS Hostname" and enter the network name of the remote computer/server.

•Message Delay. Sometimes, you may need to send HL7 messages to an older system which needs you to pause between sending messages, it's rare, but it happens. If so, enter that value here.

•Keep Connection Open. The typical HL7 message transaction works like this. 1) Connect to the target listener. 2) Send the message 3) Wait for an HL7 acknowledgement (if necessary) 4) Disconnect from the target listener. Steps 1-4 are repeated with every message. This may seem like a lot of connecting and disconnecting but it's really quite fast. Sometimes, systems (especially older systems) need you to keep the connection open until all of your queued messages are sent, if so, check this box. Note that this should be something that your trading partner tells you specifically to do. IMPORTANT: See below for extended information on KeepConnectionOpen!

HL7 Message Control Characters

In most instances you will NOT need to alter these settings. It should only be necessary if you are sending HL7 messages to a client who is using non-standard control characters.

•BOM. The beginning of message character(s). All HL7 messages sent to the listener must begin with this character(s). The ANSI HL7 standard is a single Hex (0B) character

•EOM. The end of message character(s). All HL7 messages sent to the listener must end with these character(s). The ANSI HL7 standard is a Hex (1C) followed by a Hex(0D)

•SOM. The HL7 message segment delimiter. HL7 messages are made up of 'Segments'. The segments must be separated by this character(s). The ANSI HL7 standard is a single carriage return character  (a Hex(0D) ). NOTE ABOUT BOM, EOM characters: Messages contained in your HL7 data files DO NOT have to contain BOM and EOM characters, but IF they do then they MUST match these settings. If your HL7 messages DO NOT already have the BOM and EOM characters the router profile will add them when it sends the HL7 message.

 

File System Settings

As each profile executes it will look for HL7 data files that are written to the data folder (see below). Each file in the data folder can contain one or many HL7 messages. When HL7 data files are detected by the profile each file is opened up and all HL7 messages are extracted and placed in a sub-folder of the data folder called 'UPR_Queue' until the profile can actually send them to the client listener.

•Data Folder. The full path to the folder where HL7 data files will be stored. IMPORTANT NOTE: This folder should always be on a local drive. If you need to use a network share, mapped drive or virtual drive see Troubleshooting for more information.

•Extension. The file extension that the profile should use when looking for HL7 message files in the data folder.

•Service Instance #: Indicates which of the three available UltraPort Routers Services should run this Router Profile. Note: This property is N/A if you are running with a Demo or Developer license.

 

 

 

---

---

 

 

Optional Router Profile Settings

 

 

NEW In version 5! Enable or Disable extended "Debug" logging. If checked then the normal daily event logs are greatly expanded with more event notifications.

 

HL7 'Wait for Acknowledgement Settings'

You should know whether your trading partner's HL7 listener is going to send you HL7 acknowledgements before you start sending them messages. If you're not sure, ask them. It's not an unreasonable question.

•Always. After sending each message the profile will ALWAYS wait for the client to return an HL7 acknowledgement.

•Never. The profile will NEVER wait for an HL7 acknowledgement and will ignore any that it does receive (IE they are NOT archived, even if configured to do so in the global settings).

•Automatic. The profile will determine whether to wait for an HL7 acknowledgement based on the content of fields 15 and 16 of the MSH segment of the message.

•Wait for how long. If you choose Always or Automatic, then how long should the profile wait for the acknowledgement before giving up and either resending the message or logging the message as unacknowledged and storing it in a sub-folder of the data folder called UPR_Unacknowledged. NOTE: It's a popular misconception that setting this to a high value will slow down your processing. This is NOT TRUE. Your profile will process as quickly as it possibly can at all times, if the other side is SUPPOSED to send you an acknowledgement and it takes them 3 seconds (which is an ETERNITY in TCP/IP time which is measured in milliseconds) to do it then you should wait that long and any delays are not your fault, but rather that of the client receiving the messages and taking so long to respond. If your client returns the acknowledgement in 20 milliseconds then your profile logs it and sends the next message immediately (unless you have configured a Message Delay).

•Retry Count. Ok, your profile has sent the HL7 message to the client listener, it is expecting an acknowledgement back AND it has waited the allotted amount of time without getting one. How many times should this profile try and resend the message before giving up.

•Acknowledgement is ABSOLUTELY required. Resend forever if needed: This is really a VERY dangerous setting. If checked the router profile will ignore the Retry Count and continue to resend the HL7 message forever until either A) an HL7 ACK of some kind is received OR B) The message data file is physically removed from the UPR_QUEUE folder.

 

Message Forwarding

A unique feature of the UltraPort HL7 Router is the ability to have HL7 messages forwarded to it for delivery by a Proxy application written in Microsoft Visual Studio .Net (see the Proxy Toolkit for more information).

•Receive HL7 Messages from a Proxy Application. Check this box to enable message forwarding.

•Interface Port Number. On which TCP/IP port number will the proxy application send messages to this profile. Here's how it works. The profile will actually open it's own customized HL7 listener and wait for HL7 messages to be sent to it by Proxy applications. When messages are received they are funneled into the router's queue to be sent on to the final destination. It is even possible for many different proxy applications on many different computers to send HL7 messages to the same router profile on the same port at the same time.

 

Message Control ID (MSH Field 10)

When sending HL7 messages over TCP/IP the message control id (MSH field 10, component 1) is of vital importance. It is the field used by the receiving listener to uniquely identify and acknowledge each message. It is one of the few REQUIRED fields in the HL7 standard and has been since the beginning. This field must not be blank and SHOULD contain a value that is absolutely unique for each message between the sender and the receiver. In other words if System A sends System B an HL7 message with a control ID of 0000001 it is assumed that System A will NEVER send a different HL7 message to System B with that control ID (or at least until all available IDs are exhausted). If your messages either don't contain a control ID OR the system producing the messages uses questionable logic in creating it, you can instruct the  UltraPort Router profile to correct this error by generating a unique message control ID for you before it sends the messages out. The settings are:

•Do Not Replace. Profile does nothing

•Replace Only if Blank. As it says, if the control id is blank in the outbound message one will be created for it.

•Always Generate a Unique Control ID. All messages sent by the profile will have a unique message control id placed in field 10 of the MSH segment.                                                                                

 

Keeping the connection with the listener open

 

The 'Keep Connection Open' checkbox

 

When sending HL7 messages over TCP/IP you have the option of instructing the router profile to "Keep the connection open" with the HL7 listener. When checked the profile will not reset the listener connection after each transaction (resetting is the default, preferred behavior with modern HL7 software). This option is only provided to maintain backward compatibility with older or non-standard HL7 listener software and you should not check it unless it is an absolute requirement of your HL7 trading partner (the listener).

 

A brief explanation. Modern HL7 listener software products (like the UltraPort HL7 Listener) are (or should be) designed using the MLLP protocol. This means that (for want of a better description) they work similarly to WEB servers and can accept multiple connections from different client (router) software. However, as with everything, there are only a finite number of connections which they can accept at any one time. For this reason the "proper" way (as defined by HL7 standards) to send an HL7 message over TCP/IP is to repeat the same 4 steps for every HL7 message sent:

1.Establish a connection with the target listeners port number.

2.Send a single HL7 message

3.Wait for an HL7 acknowledgement (if required) and if not received go back to step 2 (see Optional Router Settings for more info)

4.Disconnect from the target listener

While it may seem like this method would significantly slow performance it truly does not. The REALLY time consuming part of exchanging HL7 is in establishing the NETWORK connection to the target HL7 listener (if it's on a remote computer) which IS persistent and has already been done before the router profile tries to establish a connection to the target listener port. Older (or non-standard) HL7 Listeners were not MLLP listeners but were PORT listeners and could only accept a single inbound connection.

 

What are the ramifications of keeping the connection open? There can be several and while none are patently critical (for you) you should be aware of what they are. First and foremost you need to understand that by keeping the connection open you are monopolizing one connection to the target listener. This may be fine and in fact may be the intended behavior.

 

The next thing to understand is an internal limitation of the UltraPort Router. In the MicroSoft .Net framework which we use after a connection to a listener is successfully opened, the only way to successfully determine if it is TRULY open and working is to try and transmit data to it (ie sending an HL7 message). If the connection is kept open AND it is idle (meaning there are no messages to be sent) AND that connection is force closed (either by the target listener stopping or a network outage of some kind) the router profile is unaware that anything has happened and receives no event telling it this. A side effect of this (which is really a known BUG but MicroSoft currently documents it as a 'behavior') is that the underlying kernel of the .Net frameworks network library does detect the broken connection and the socket goes into an infinite loop trying to correct itself (which it cannot do EVEN if the network/listener connection is restored). This can cause the system CPU monitor to display excessive CPU usage by the UltraPort Router. The good news is that if this happens it is NOT disabling your system and any other router profiles which are connected are still running normally. This problem would automatically correct itself the next time that the profile attempts to send an HL7 message. If the attempt to send the message fails, the connection is force closed and the CPU usage returns to normal.

 

What can be done to address this issue?  The first thing that can be done is to NOT keep the connection open with the target listener unless absolutely necessary. We realize that this might not be possible for everyone and so we have addressed the issue here by implementing the following change in the UltraPort Router behavior.

 

Beginning in version 1.6.1 (And Ending with Version 5.0) we addressed this issue by having each router profile monitor it's connection status every time that it checks the data folder for new HL7 messages (by default this is every 10 seconds) to be sent out. If the listener connection is indicating that it IS open the profile will implement the following behavior:

 

1.It will verify the amount of time since the last HL7 message was successfully sent to the target listener. If it is less than 2 minutes then it does nothing.

2.If it has been more than 2 minutes since a message was successfully sent then the profile will call the operating system to get the total CPU usage. If it is less than 50% then it does nothing. The CPU usage is determined by taking 5 samples 1 millisecond apart and using the highest reading.

3.If the CPU Usage is 50% or greater it will place an entry into the profile log file indicating that it will force close the connection soon. Profile log files are kept in the program installation folder.

4.If the CPU Usage remains at 50% or greater for 3 folder polling iterations (maximum 30 seconds) and the connection is still reading as idle and open then the connection to the target listener is force closed.

Now this behavior can have ramifications on customers who need the connection to stay open AND are running on computers which have CPU usage spikes. This behavior can be remedied by having your application send an HL7 "Keep Alive" message to the target listener every few minutes if there are no other messages to send. NOTE: the keep alive message is not necessarily supported by the target listener. Contact that vendor for help. The UltraPort and EasyHL7 listeners do support the keep alive message as they will accept any HL7 message.