Please enable JavaScript to view this site.

CORE HL7 TCP/IP Listener

Creating or Editing a Profile

Creating or Editing a Profile



A CORE HL7 Listener 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 PLUS Enabling or Disabling your listener and assigning it to a Windows Service to run, 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 Listener 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 Port Number. In HL7 TCP/IP communications it is most often the entity running the LISTENER (that's you) who gets to decide the HL7 listener port. You can enter any valid port number in this field which is NOT being used by another Listener profile OR some other TCP/IP Listener. For example, Microsoft SQL Server is a "Listener", it "Listens" for SQL traffic on port #1433. If you created a CORE HL7 Listener profile and assigned it port 1433 AND the server was also running Microsoft SQL Server, something bad would happen. Either your Listener won't work OR SQL Server won't work. A good rule of thumb is to use a port number between 2048 and 65535.

3.The Data Folder. When a HL7 message is received, we have to put it somewhere. This Windows folder is where your profile will write the HL7 messages as they come in. They will be placed into uniquely named individual files with only 1 message per file. 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.

4.Section 5. Enabling your profile and assigning it to a Windows Service. NEW in version 1.5 you can assign your Listener profiles to run in a Private Service!


As explained above, if you fill in these fields then you are very likely done. Just click Ok and your Listener profile complete.


Listener Profile Fields By Section

Creating or Editing a Profile

Creating or Editing a Profile


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 Listener profiles. We use the ID field when creating files on the file system to make sure that if you have multiple listener 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.


Port Number: Explained in the section at the top of the page. Your rule of thumb is to choose a Port Number between 2048 and 65535.


Send Acknowledgements:  When your Trading Partner sends you a HL7 message they will expect you (your CORE Listener) to send back a HL7 ACK indicating that you have received and accepted the message. In this field you have 3 choices, Automatic, Always, and Never. Always and Never are self-explanatory, choosing Always your CORE Listener will send an ACK for every message, and Never means that we do NOT send back an ACK. If you check Automatic (which is the default) your Listener will look at the MSH segment of the incoming message and determine IF the Trading Partner is expecting an ACK and if so, it will send the ACK.


Include Message Event (MSH 9.2): A HL7 ACK is itself a very short HL7 message. The message type (MSH 9.1) is always ACK. Some Trading Partners might also want you to echo the message event (MSH 9.2) of the HL7 message being acknowledged in the ACK message. Checking this box will make this happen.


Mirror Control ID (MSH 10.1):  As explained above, the ACK is a fully formed HL7 message. As such your CORE Listener will assign it a unique Message Control ID (MSH 10.1). Some Trading Partners might insist that you echo the Message Control ID of the HL7 message being acknowledged and use it as the Message Control ID in the ACK message. Checking this box will make that happen.


Use CA/CE Acknowledgement Types Instead of AA/AR: Part of the ACK message is the Acknowledgement Type. The most common Types are AA (accepted) AR (rejected) or AE (error). Your CORE Listener will always return the AA Ack Type unless an error occurs writing the HL7 message to the Data Folder (Section 3)in which case it will return an AE ACK and then stop listening for new messages until the problem with the Data Folder is fixed. In rare occurrences your Trading Partner might insist that you send back a CA or CE Ack Type. CA and CE are conditional. CA means Conditionally Accepted. CE means Conditional Error.


Section 3.


Data Folder: Explained at the top of this page. This is the folder where your CORE HL7 Listener will store HL7 messages.


File Extension: The file extension to use when creating HL7 message files in the Data Folder. The default is hl7 but you can change this to whatever you like.


Use a Traffic Throttle: Your CORE HL7 Listener is very fast. We have bench-marked it as being able to receive, write to file, and ACK more than 80 messages per second using a USB thumb drive as the Data Folder. That being said it is possible to overwhelm a listener with inbound traffic. Consider this scenario: You have purchased the CORE HL7 Listener (Enterprise) license and you are running 50 listener profiles with 50 different Trading Partners on a virtual machine. 49 of your clients are sending constant traffic, say 4-5000 messages per hour, but one of your clients is using a custom device designed, dedicated, and optimized to deliver HL7 messages at high speed. These devices are beasts, they can deliver 250 messages per second or more over a fast VPN connection and they can cost US$20-40,000.00. What you might want to do in a situation like this if to check this box and use a Traffic Throttle. What this does is tells your Listener to implement a tiny delay (set by you when you check the box) before sending back the HL7 ACK, effectively slowing down the incoming traffic.


Section 4.


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


Windows Service Assignment: The CORE HL7 Listener gives you 4 MS Windows services for you to use PLUS the ability to assign your profile to a Private Service. What you might want to do, if your license allows for multiple ports, is split them up amongst the 4 services and / or use the Private Services option.


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


Advanced and Optional Settings

Creating or Editing a Profile

Creating or Editing a Profile


Section 6.


Include the TCP/IP Envelop Characters (BOM & EOM):  When your CORE Listener receives HL7 messages it will by default remove the TCP/IP Envelope (the BOM and EOM) characters. Check this box and these characters will be left in place in the resulting data file when it is created (see Message Handling).


Section 6. Export 'Raw' HL7 Received


By default your CORE HL7 Listener will optimize the HL7 messages received before writing them to disk. Choose this option and the 'RAW' HL7 is written to disk instead as is done when Malformed Messages are received.


Section 6. Optimize the HL7 Messages


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




First of all you should never receive 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:




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




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




Transform the Message or Acknowledgement: This is a new feature in version 1.5 which allows you to do some manipulation of the HL7 message before it is written out to the Data Folder OR to the HL7 Acknowledgement before it is returned to the Sender. See Transformations for more information.


Section 7.


Text Encoding (ADVANCED): 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 8.


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.




Keyboard Navigation

F7 for caret browsing
Hold ALT and press letter

This Info: ALT+q
Nav Header: ALT+n
Page Header: ALT+h
Topic Header: ALT+t
Topic Body: ALT+b
Exit Menu/Up: ESC