Sending and Receiving HL7 Messages

HL7 Messages are normally sent using the MLLP protocol.  For those that are interested, that just means there are a couple of characters at the front of the message to signify the start, and a couple of characters at the end the signal the conclusion of the message.  Other than that it is really just plain text.  For the most part though you don’t really have to worry about MLLP at all as most HL7 software is just going to handle it for you.  You’ll see in my illustrations that I’m using HL7 Soup which is probably perfect for most people too.

I’ll start by creating a test where I just send the message from HL7 Soup back to the same instance of HL7 Soup.

Start by configuring the receiver by clicking on the drop down for the “Receive” button and selecting “Create New”.  You’ll then be presented with the Receiver configuration dialog.

Here you configure the receiving address and port for you message.  For the more technical readers, you’ll notice that this configuration is for TCP communication.  MLLP sits on top of this. 

Because we are sending to ourselves we will use the server address of 127.0.0.1, which is just a relay address according to TCP\IP.  It will send the message straight back to the sender.  The default port HL7 Soup uses is 22222, but you are welcome to change this as required.

So that’s it.  Basically you can just load up this dialog and accept the defaults and you are done.  Your welcome to change the Name if you like, but then just click ok and your receiver is created.

If only creating the sender was that easy.  Actually, only joking – it is exactly the same for creating the sender.  Just click the “Send” button, the send dialog loads, accept the defaults, click ok and you’re done.

You can now send a test message by clicking “Start Receiving”, the clicking the “Send” button a few times.  You’ll see the message going through, and the responses coming back too.  If not then see further on in this document for the trouble shooting section.

HL7 Message once received should always return a response to the sender that lets them know everything went ok. An Application Accepted response message (AA) signifies the message was received and processed without problems.  If things went wrong then an (AE) is sent, and if the message was rejected it’s an ER.  HL7 Soup shows these in different colors so that they are easy to spot. You also have the option to load only successful, errored, and/or rejected messages into the UI, and you can also configure the receiver to respond in a fixed manner to help with testing. 

Sending to another computer on the same network is exactly the same process, just the addresses are a bit different.  It also can be a bit fiddler because of firewalls etc.

All you need to do is adjust the Server IP address for both the Sender and Receiver configurations to be the IP address of the Receiver.  Yep, they will both have the same IP address, and they will both have the same port.

So how do you get the IP address I hear you ask?  Well when you are on the Receiving computer just load up a command prompt and type ipconfig.

Here you will find the IP address that should go into the configuration.  Note that you don’t need to use IP addresses, and it works perfectly well with DNS too.  That means the Server text box can just be the name of the computer.

That’s it, you should now be able to just start the receiver, and click send a few times to watch you messages fire across.

Troubleshooting:

Although it’s normally pretty straight forward there are a number of things that could go wrong, so here is a list of things worth checking:

1. Make sure that the ports are the same on the sender and the receiver.

2. Make sure the Server address is the same on the sender and the receiver.

3. If you are using IP Addresses in the Server text box then change to the computers network name, or vice versa.

4. Ping the receiver from the sender to make sure they can talk over the network.

5. Turn off the windows firewall on both computers (or configure HL7 Soup to be allowed to use the desired port by whatever means your firewall allows)

Please let me know if there is anything else that should be added to this list and I will add it to help others.