- Introduction
- Send messages with the HL7 Simulator
- Receive messages with the HL7 Listener
- More Information
Introduction
Sending and receiving HL7 test messages: Two utilities are available the HL7 Simulator and the HL7 Listener.
HL7 Simulator
The HL7 Simulator is a useful tool for simulating a live feed of HL7 messages. Effectively, it acts as a simple HL7 TCP/IP client.
Two versions of the HL7 Simulator are provided: a GUI application and a command-line application.
HL7 Listener
The listener operates as a TCP/IP server which is listening on a port number. The application that you wish to receive messages from must be configured to connect via TCP/IP as a client to this port on the host that the listener is running on.
Getting HL7 Sample data
Getting ones hands on HL7 data is one of the biggest pains in the proverbial even for us. See our Getting Sample HL7 Data article for details on generating data and a few sources of sample data. If you have some good quality sanitized sample/test HL7 data please send it to us and we will happily post it on this site.
Send messages with the HL7 Simulator [top]
The Simulator can be used through Windows GUI, or as a command-line application.
Using the Simulator GUI
Run the HL7 Simulator by clicking Start > Programs > iNTERFACEWARE > HL7 Analytical Tools > HL7 Simulator.
The following screenshot explains the various settings available for the HL7 Simulator GUI application:
The Simulator reads each message from the log file, and attempts to send it to the host using the port number specified on the form. The port number is specified in the LLP Listener Connection Settings Port settings (though you can use any llp listener host + port, it does not even need to be Iguana).
When it receives an ACKnowledgment message from the receiver, if the Keep sending messages when ACK received check box has been selected, it will send the next message in the input file.
If it does not receive an ACK message in the required Time out period, the simulator will attempt to resend the last message, repeating the action up to the number of retry times specified in the Retry Count box.
The time delay box specifies how much time to wait after getting the ACK message from the receiver before sending the next one.
Note: The simulator can also be used to deal with odd systems which do not follow the standard HL7 practice of ACKnowledging on the same port as the sender. These systems expect to be able to send their ACKnowledgement messages back to the sender on another socket that the sender is listening to.
By selecting Receive ACKnowledgement Messages via Server Socket, the Simulator can be configured to expect the ACK messages to come back via the port number specified in the box below. This is quite unusual and should not be necessary for most users.
Tip: The HL7 Simulator GUI does not run on the Mac, but you can easily send messages from a Windows machine, simply enter the network address or network name of the target machine in the Host field. For example, when running the Simulator in a Parallels VM, just use the IP address for the Mac (from advanced network setting in system preferences).
Using the Simulator Command Line Application
The command-line version of the HL7 Simulator is named hl7simulator. Where it is located depends on the operating system that you are using:
- In the Windows environment, hl7simulator is located in the directory in which Chameleon is installed (for example, C:\Program Files\iNTERFACEWARE\Chameleon).
- As of version 4.1 of Iguana, hl7simulator is provided for the Linux and Mac OS X environments. It is located in the directory in which Iguana is installed.
When you start hl7simulator from the command line, you must provide three parameters:
- The host IP address or name to which messages are to be sent;
- The port number to use;
- The file containing the HL7 messages to be sent.
The syntax for hl7simulator is:
hl7simulator --host <host> --port <portnum> --source_file <filename> [<additional optional parameters>]
The following table provides a complete list of the parameters that can be provided to hl7simulator. These parameters can appear in any order.
| Parameter | Description |
|---|---|
| –host <host> | The host to which messages are to be sent. <host> can be an IP address or a host name. This parameter must be provided. |
| –port <portnum> | <portnum> is the port number to use when sending messages. This parameter must be provided. |
| –source_file <filename> | The file containing the HL7 messages to be sent. <filename> specifies the path and file name of the file. If no path is specified, the file is assumed to be in the current directory. This parameter must be provided. |
| –multiple_connect | Disconnect from the host after sending a message, and reconnect when sending the next message. |
| –reconnect_attempts <num> | If not able to connect to the host, try to reconnect <num> times before giving up. If <num> is 0, or if this parameter is not specified, keep trying to reconnect forever. |
| –retry_count <num> | If a message is not sent successfully, try to resend the message <num> times before giving up. If this parameter is not specified, a retry count of 10 is used. |
| –run_once | Only send the messages once; stop when the end of the message file is reached. If this parameter is not specified, hl7simulator sends the messages in the message file repeatedly until terminated. |
| –time_delay <time> | The amount of time to wait, specified in milliseconds, before sending the next message. If this parameter is not specified, a delay of 100 milliseconds is used. |
| –timeout <time> | The amount of time to wait for an ACKnowledgment message from the host before resending a message. <time> is specified in milliseconds; if <time> is 0, hl7simulator will not wait for an ACK. If this parameter is not specified, a timeout of 1000 milliseconds is used. |
Here is an example of the output from hl7simulator:
D:\sample>hl7simulator --port 1234 --host localhost --source_file messages.txt --run_once hl7simulator 1.0.4 -------------HL7 Simulator Started at 17/2/2009 13:31:15------------- Connected to host. Message #82 Time Taken : 9 seconds TPS : 9.111112
As messages are sent, a running count of the message total is displayed in your command prompt window. When hl7simulator stops running or is terminated, it displays the total elapsed time and the number of messages sent per second (shown here as TPS, or transactions per second).
Note: To terminate hl7simulator, type Ctrl-C (press the Ctrl and C keys simultaneously).
If you try to run hl7simulator when there is no Iguana channel listening on the port you specify, you will see messages similar to the following:
D:\sample>hl7simulator --port 1234 --host localhost --source_file message.txt --reconnect_attempts 3 hl7simulator 1.0.4 -------------HL7 Simulator Started at 17/2/2009 13:39:31------------- Error: No connection could be made because the target machine actively refused it. Retrying connect in 1000 ms Error: No connection could be made because the target machine actively refused it. Retrying connect in 1000 ms Error: No connection could be made because the target machine actively refused it. Retrying connect in 1000 ms Connection failed: Connection attempts failed Error: Unable to send a message. Time Taken : 6 seconds TPS : 0.166667
In this case, the –reconnect_attempts parameter specifies how often hl7simulator will try to send the message before giving up.
HL7 Simulator Input file format
The HL7 Simulator takes a text file with HL7 messages in it as its input. Messages from this text file are replayed as a client TCP/IP program using the LLP protocol.
The Simulator is very specific about the format of this message input file. This format requires each message to be formatted on a single line with 0x0D characters separating the segments, and a line feed (0x0A == 10 == \n) and carriage return character (0x0D == 13 == \r) sequence at the end. In an editor like notepad when word wrap is off, it appears like each message is one line in the file.
Note: The easiest way to get files to use the Simulator is to use the HL7 Listener.
The input file cannot be shared by two running instances of the Simulator or Listener. If multiple instances of these applications must be run, each must have its own input/output file.
Note: From version 3.211 and above of Chameleon the simulator is able to handle lab report messages with embedded \n (0x0A) characters in textual data. This is a valid use of the HL7 standard. However, always ensure the messages in your log file do not have embedded \0x0D characters in the textual data since this is illegal. The Simulator looks for \r\n at the end of each message in the log file.
Receive messages with the HL7 Listener [top]
Run the HL7 Simulator by clicking Start > Programs > iNTERFACEWARE > HL7 Analytical Tools > HL7 Listener.
The HL7 Listener is a GUI application, unlike the HL7 Simulator there is no command-line version.
Using the HL7 Listener
The following screenshot explains the settings available for the HL7 Listener Utility:
The Parse delimiter characters from MSH segment checkbox is referring to the HL7 protocol which allows the redefinition of the delimiter characters in the MSH segment. Normally this should just be left checked. However, it can be useful if incoming messages have incorrectly formatted MSH segments.
Each incoming message is “ACKnowledged” by the HL7 listener and logged into the specified message log file. Each message is formatted in a single line with 0x0D characters separating the segments and a line feed at the end of each message. In an editor like notepad when word wrap is off, it appears like each message is one line in the file.
The log file cannot be shared by two running instances of the HL7 Simulator and Listener. If this is required, a different log file should be specified for each application.
The log file can then be used in the HL7 Simulator to replay the flow of messages. The HL7 Simulator is very specific about the input message log file format. As a result it will only accept the format generated by the HL7 Listener.
Note: The Listener needs exclusive access to that the port it is listening on. It’s not possible for other applications to listen at the same time to the stream of HL7 messages that the listener is receiving.
How the HL7 Listener works
The HL7 Listener uses an Auto ACKnowledgement to generate ACK messages. The settings used to configure the format of the ACK messages are stored in the listener.vmd, which ships in Chameleon‘s application directory (e.g., C:\Program Files\iNTERFACEWARE).
Note: Sometimes you might need to change the listener.vmd file when dealing with systems which are not HL7 compliant. For instance, you might use an Iguana Filter script to remove illegal embedded 0x0D characters.