Creating CORE HL7 TCP/IP Sender Profiles

 

 

 

 

 

 

A CORE HL7 Sender profile might seem complex on first glance, but it's really not. When you click on the New button in the Main Window and open up the Create/Edit a profile window there are typically (95% of the time or more) only 3 empty fields that you need to fill out or change and you can accept the 'Default' values on all the other fields. These fields are:

 

1.The Profile Name. Just enter a free form name for your Sender profile which you have not already used for another profile (if you have a multiple ports license). You have to have the unique name so that you can identify your profile in the list of profiles on the Main Window.

2.The Destination. This will include the Port Number and (if sending to a remote computer / server) the TCP/IP Address. In HL7 TCP/IP communications it is most often the entity running the Listener who dictates the Port Number.  A good rule of thumb is to use a port number between 2048 and 65535.

3.The Data Folder. This folder (combined with the File Extension) will be where your profile will search for HL7 files containing messages you wish to send. IMPORTANT: If at all possible we recommend that you use a folder on a LOCAL hard drive rather than a network share, NAS drive, or mapped drive. This is not say that you cannot use these network drives, but if you do, it might add another level of complexity to your system when it comes to running your Windows Services.

 

As explained above, if you fill in these fields then you are very likely done. Just enable / disable the profile in Section 5 and click Ok and your Sender profile complete.

 

Sprinkled across the screen you will see independent Help buttons () which you can click for a brief explanation of the nearest item and an option to open this help document.

---

Sender Profiles By Section

 

Section 1.

 

 

 

Profile Name: Explained in the section above.

 

ID (Short Name): The ID field will be automatically populated but you can also change it if you like. The ID is a very short (2-4 characters) value which, like the Profile Name, must be unique in all of your Sender profiles. We use the ID field when creating files on the file system to make sure that if you have multiple Sender profiles they don't overwrite each others logs or messages. For instance, you might have 2 profiles which point to the SAME data folder. The system will create the file names using a date/time stamp + ID + File Extension (in Section 2). This way even if your 2 profiles received a HL7 message at the exact same instance the file names will still be unique.

---

Section 2.

 

 

 

 

Where is the HL7 Listener? The first thing you need to tell your profile is where the HL7 Listener which is to receive your HL7 messages is running. Is it on the same computer as your CORE HL7 Sender? Or is it on another (remote) computer? If the listener is running on a remote computer you will have to enter a TCP/IP address for that computer. If it's on the same computer your profile will "figure out" which TCP/IP address to send to on the local machine. NOTE: Even if the HL7 Listener software is running on the local computer you CAN check On another computer and enter a specific TCP/IP address on the local computer.

 

Port Number: Explained in the section at the top of the page. Your Trading Partner will tell you which Port Number they are "Listening" on.

 

Keep the Connection with the Listener Open: This is an important property and can be dangerous to use depending on your other settings. If checked your CORE HL7 Sender will try and keep a persistent TCP/IP connection with the receiver (HL7 Listener at the destination) open even when there is no outbound traffic. This is NOT really HL7 Standard behavior and we provide this because some Trading Partners using older or poorly written HL7 Listener software may require it. The trick to this setting is this. If you don't KNOW whether it needs to be checked, then don't check it. Review Sending HL7 Over TCP/IP for more information about exactly how HL7 messages should be exchanged over TCP/IP.

 

Delay between each message: Your CORE HL7 Sender(s) can send messages very, very, quickly. Many HL7 Listener software packages (like our CORE HL7 Listener) can receive HL7 messages very, very, quickly. You may encounter a Trading Partner (and some of our clients have) who needs you to regulate your traffic speed to allow them adequate time to process incoming messages. Of course, since YOU are the one creating the HL7 messages and placing them into the Data Folder to be sent you can ultimately control the traffic flow, but this setting allows you an option to do it right in your profile. You can select a small delay value and your profile will automatically wait that amount of time between messages. NOTE: This setting is in addition to and not in place of any wait for acknowledgement timeout settings you have implemented in the next section. This is another property where "If you DON'T know whether you need it, you DON'T need it".

---

 

Section 3.

 

 

 

Section 3 is very important. There is a detailed discussion of why in Sending HL7 Over TCP/IP but in a nutshell what you need to remember is this: Exchanging HL7 messages over TCP/IP is supposed to be a transaction. You send your Trading Partner a HL7 message which begins the transaction, and they send you back a HL7 Acknowledgement verifying that they received the message which completes the transaction.

 

Speed. This is why when we are asked "How fast can the CORE HL7 Sender deliver HL7 messages?" we can only answer "It's capable of sending messages very, very quickly". How fast a message can be delivered is immaterial, what matters is how fast the transaction can be completed, which takes both sides of the equation into account. If we can deliver 10 messages per second (and we can and more) but the HL7 Listener on the other end can only receive, process, and acknowledge 1 message per second, then our "speed" will be a maximum of 60 messages per minute, PERIOD, FULL STOP.

 

Wait for the HL7 Acknowledgement:  When you send your Trading Partner HL7 message how should the profile know whether to wait for a HL7 Acknowledgement. In this field you have 3 choices, Automatic, Always, and Never.

 

•Automatic. When checked your profile will examine the HL7 message being sent to determine IF a HL7 Ack is expected or not. It does this by looking at field 15 of the MSH segment (Accept Acknowledgement Flag) and unless that field explicitly says that no acknowledgement is expected with a value of NE (never) we assume that the acknowledgement is expected and we will wait for it. If the field is blank, we wait. If the field is missing from the MSH segment, we wait. If the field has the word "MAYBE" in it, we wait.

•Always. Fairly self explanatory. We will Always wait for a HL7 ACK message.

•Never. Also fairly self explanatory, but beware. You should never check this option unless you have an explicit agreement with your Trading Partner and they insist on it.

 

Wait How Long: For (Automatic and Always). After your profile has successfully delivered the HL7 message, how long should we wait for the receiving HL7 Listener to respond with an acknowledgement of some kind. NOTE: This setting is often misunderstood. Read the discussion at the top of this section about speed. Your selection for this setting has nothing to do with you, it's for the other side. The default value is 5 seconds, if the other side responds and sends the ACK back in 10 milliseconds (our CORE HL7 Listener can do this) you're going to exchange about 600 messages per minute. If they take 3 seconds, you're going to exchange about 20 messages per minute. When you are setting up your HL7 interface this is one of the things that you need to discuss with your Trading Partner, IE how long do they NEED. Then take what they tell you and choose a setting with a bit more cushion for safety.

 

If no ACK is received try again: For (Automatic and Always). This is the Resend behavior. IF we successfully deliver a HL7 message, AND we are expecting an ACK to be delivered within the <Wait How Long> timeout, AND it does not arrive, how many times should we resend the message before we give up? NOTE: You should ALWAYS have a value of 1 or more here. NOTE: This is a RESEND. This means that we send it once, then RESEND it this many times. If you choose 2 here (the default) the message will be successfully delivered to the receiver 3 times in total before we give up.

 

 

---

Section 4.

 

 

 

Data Folder: This is the folder where you (whatever system actually produces the HL7 messages) will place data files containing HL7 messages. Your data files must contain at least 1 message per file and may contain many messages. NOTE: If at all possible you should choose a local folder here rather than a network share, mapped drive, or NAS drive. You can use those network resources but you will need to review the Running Windows Services section on extra configuration which you might have to do when using network folders.

 

File Extension: Here you will enter the file extension the profile should look for in the data folder. You enter only the file extension, no wildcard characters or periods.

 

---

 

BOM, EOM, and SOM:  These are the Beginning of Message (BOM) End of Message (EOM) and HL7 Segment Delimiter (SOM). These characters make up the TCP/IP envelope used by the HL7 Sender. The values are shown in HEX and the default values (as seen in the screen shot above) are the ANSI standard values for HL7. You should NOT have to change these values from their default values unless your Trading Partner explicitly indicates that they are deviating from HL7 standards and using different values. You can click the  button next to each field to change these values. The Reset button will change all 3 values back to their ANSI defaults.

 

Restart Sender if idle for too long: Checking this box might help if your VPN connections are, shall we say, less than reliable. It will tell the profile to reset itself (stop and restart) if no HL7 messages are received for the time specified by you.

 

Section 5.

 

 

 

Profile Enabled: Check or uncheck this box to enable/disable your Sender profile.

 

Run this profile in Windows service Instance: The CORE HL7 Sender gives you 4 MS Windows services for you to use. What you might want to do, if your license allows for multiple ports, is split them up logically amongst the 4 services. There is no "right" or "wrong" selection here. Note that starting in version 1.5 you can also select Private Service here to run your profile all by itself in a Windows Service (see Private Services).

 

 

 

 

When done click Ok to save your profile or review the Advanced and Optional Settings.

 

---

 

Advanced and Optional Settings

 

 

 

 

 

Section 6.

 

 

 

The TCP/IP Envelop Characters (BOM, EOM, and SOM)  When your CORE Sender sends HL7 messages it will wrap the message in the TCP/IP Envelope (the BOM and EOM) characters. Your system does NOT need to include these characters when writing HL7 messages to the data folder, but if you do it will not generate an error. Just click next to any setting to change. NOTE: You really should NEVER have to change these settings from the ANSI Defaults unless you have an explicit agreement with your Trading Partner to do so.

 

---

 

Section 7.

 

 

 

By default your CORE HL7 Sender will optimize the HL7 messages received before sending them to your Trading Partner. We recommend the optimizations but you can check Send only the 'Raw' HL7 data and your profile will deliver the HL7 data exactly as it is loaded from the data file(s).

 

Optimizing the HL7 Messages

 

Trim empty trailing fields from the end of each segment: When you elect to have your CORE HL7 Sender optimize the HL7 messages this feature is automatically enabled. If your HL7 message has a segment value like:

 

XYZ|1|SomeValue|Smith^John|||||||||||||

 

First of all you should never produce a HL7 segment that looks like this. HL7 standard optimization rules dictate (and have for 25 years) that the message processor creating or reading the message should automatically remove trailing fields which are empty so that the resulting segment value would look like this:

 

XYZ|1|SomeValue|Smith^John

 

Optimize the HL7 Messages (Continued)

 

Force a final segment delimiter in each message: HL7 rules say that a HL7 message is made up of HL7 segments and that each segment must end with a segment delimiter (SOM) EXCEPT for the FINAL segment in which it is optional. Check this box and your CORE HL7 Sender will ensure that the final segment of each message ends with a segment delimiter.

 

Force every segment to end in a Field Delimiter: As explained above, when you optimization is selected we will automatically enforce the HL7 standard optimization and trim trailing fields. Some customers however might require that every field in a segment have a closing delimiter. Checking this box will take care of that. Using the example above from Trim empty trail... :

 

XYZ|1|SomeValue|Smith^John|||||||||||||

 

Trailing fields would be trimmed BUT your CORE Sender would ensure that the segment ended with a Field Delimiter so your resulting segment would look like this:

 

XYZ|1|SomeValue|Smith^John|

 

Optimize the HL7 Messages (Continued)

 

Replace Message Control ID: When exchanging HL7 messages over TCP/IP the Message Control ID (MSH 10.1) is absolutely essential. We deliver a HL7 message with Message Control ID = "123ABC" and the Listener responds with a HL7 ACK which says "We received Message Control ID 123ABC". If you are creating the HL7 messages being sent then your system should already be handling this by assigning every HL7 message a unique Message Control ID. The CORE HL7 Sender gives you the option to insure that this is done. You can check this box and have 2 options, Only if it's blank and Always.

 

IMPORTANT: Your CORE HL7 Sender will NOT deliver a HL7 message unless it has a Message Control ID (MSH 10.1). If a HL7 message is detected in queue to be sent it is considered to be a malformed message and is handled accordingly (see Message Handling - Malformed Messages)/

 

 

Section 8.

 

 

 

Text Encoding (ADVANCED): (Not Enabled in this release). This is an advanced property and allows you to set a specific Windows Text encoding method. This can be important if your country uses HL7 but does not use the latin alphabet (example Russia, China, Israel) OR uses the latin alphabet but also makes extensive use of extended ASCII characters (Germany). If you are unsure or don't know what this means choosing "Default" in this section is (in the VAST majority of occurrences) a safe choice.

 

 

Section 9.

 

 

 

 

Profile Notes: A free form profile note. Can be any text value up to 5Kb in length.

---

 

 

If you are experiencing problems with your profiles and cannot find an answer on this page see Troubleshooting for more information or Contact Customer Service.