HL7TransmitterService.exe is a Windows service that is used to transmit and receive HL7 messages using the Minimal Low-Level Protocol (MLLP) over TCP/IP connections. Multiple transmitters and receivers can be configured. It includes a graphical configuration program to make it easy to set up, HL7TransmitterConfig.exe.

When used in conjunction with HL7ScriptService, together they become a powerful interface engine that can acccept, transform, and forward messages to and from numerous other systems.

Please note that these connections are unencrypted, plain TCP/IP. If you require secure connections (and you must, if sending or receiving PHI outside of your secure LAN), you are responsible for securing them using a VPN, SSL/TLS tunnel, or some other method. Personally, I am quite fond of stunnel.

Table of Contents

Setup and Configuration

Use the HL7TransmitterConfig.exe program to configure the service settings. The settings are stored in HL7TransmitterService.ini in the application directory. Each connection that you configure is either a Transmitter or a Receiver, and is stored in a separate [Section] in the ini file.

The configuration program can also install and control the service when Run as Administrator (which it does by default). Alternately, you can use "HL7TransmitterService /install" (or /uninstall) in a command prompt that was started using "Run as administrator". The service appears in the Service Control Manager as "HL7TransmitterService".

If you modify the settings after the service has started, you must restart the service to load the new values. The config program will prompt you to do this.

When the service is running, the "Start" button changes to "Connection Status". Press the button to open a dialog showing the current status, last activity time, and uptime message count for each active connection.

HL7TransmitterConfig

Return to Top

Global Settings

HL7 Transmitter Service Global Settings
Setting NameTypeNotes
Service ID string See Multiple Service Instances.
Log Filename string Log filename. May contain date substitution surrounded by %.
Logging Level string Determines how much logging is done, ranging from None to Debug.
Show Levels booleanShows the logging level of each entry into the log with a single letter like [I] for Info.
Timestamp Format string Log timestamp format. Default=yyyy-mm-dd hh:nn:ss
Days to Keep Logsnumber Number of days to keep dated log files. (0=forever)

If the service fails to start, check the log file. If the service is unable to use the log file specified in the ini file, it will try to write to HL7TransmitterService.log in the executable directory.

The log filename can contain a date replacement format string surrounded by percent signs (e.g. "D:\Logs\HL7Transmitter%yyyymmdd%.log"). When using a dated log file, logs older than the Days to Keep Logs setting will be cleaned up automatically at startup and each time the date changes.

The log date replacement is assumed to change no more frequenly than daily, but may be longer (weekly, etc.). When using a daily log file, the suggested Timestamp Format is "hh:nn:ss" since the date is implicit for all entries in the same file.

Connection-specific logs can be used to put a connection's log entries into its own log instead of the global log. These can use the same date replacement syntax in the filename as the global log. All settings besides the filename and logging level come from the global log settings (timestamp format, days, etc.). A connection-specific log will not prefix each entry with the connection name since it will always be the same.

A connection can be scheduled. There are three options: Always on (the default), a single start and stop time, or on a cycle. A cyclical schedule means it runs for X minutes on, then X minutes off. A cycle can be useful in situations where the host system can only accept one connection at a time, so you have to take turns with another transmitter. When a schedule is set, the Schedule button text will appear bolded. If a cyclical schedule is set, it will also be italicized. The button's hint will describe the current schedule. Schedule starts and stops will appear in the log at the Verbose or Debug levels.

Return to Top

Transmitters

Transmitters will connect to a remote host and periodically poll a directory for files containing individual hl7 messages. When new files are found, they are sent to the remote host. After positive acknowledgement, the original message file can be deleted or moved to an archive directory for a period of time.

HL7 Transmitter Settings
Setting NameTypeNotes
Connection Name string The name of the connection and ini [Section]. Log entries are prefixed with this name.
Disabled booleanDisable the connection without needing to delete it. Appears as strikethrough.
Schedule specialDetermine when the transmitter will connect to the remote host. See above.
Connection Log string Use a connection-specific log instead of the global log.
Connection Log Level string Logging level for the connection-specific log. (N=Use global level)
HL7 File Directory string The directory to poll for messages to transmit.
Filename Prefix string Optional, used to build the wildcard for polling.
Extension string Extension used to build the wildcard for polling.
Encoding string The sender and receiver must agree on the encoding: Default (single-byte) or UTF-8.
Port number The port the remote host is accepting connections on.
Remote Address string The IP address of the remote host.
Persistent ConnectionbooleanWhen off, a connection is made only when there are messages to transmit.
Connect Timeout number Number of seconds to wait for a non-persistent connection.
ACK Timeout number Number of seconds to wait for an ACK message before giving up.
Polling Interval number Number of seconds between input directory polling.
Max/Interval number Limits the number of files processed per interval to keep the service responsive.
Archive Directory string Path to move input files to after successful processing. (blank=off)
Archive Days number Number of days to keep archived files. (0=forever)
Transmit Delay number Milliseconds to pause between messages if your receiver can't handle heavy bursts.
Failed Tx Extension string Messages that get a NAK or transmit error are renamed with this extension.
Retries number Number of retries before renaming a message with the Failed Tx Extension.

Transmitters will maintain a persistent connection by default, keeping the TCP connection open as long as the service is running and the schedule is on. If the Persistent Connection option is turned off, a connection will be made only when there are messages to be transmitted and disconnected immediately afterwards.

If a message fails to transmit and exhausts the retry limit, it will be renamed by replacing the file's original extension with the Failed Tx Extension. If the Failed Tx Extension contains an asterisk, it will include the file's original extension. For example, "BAD" would rename "foo.hl7" to "foo.BAD", and "*.BAD" would rename it to "foo.hl7.BAD".

Return to Top

Receivers

Receivers will listen on a port for connections and save the messages it receives to a folder, one message per file. The received messages will be properly ACKnowledged.

HL7 Receiver Settings
Setting NameTypeNotes
Connection Name string The name of the connection and ini [Section]. Log entries are prefixed with this name.
Disabled booleanDisable the connection without needing to delete it. Appears as strikethrough.
Schedule specialDetermine when the receiver will accept connections. See above.
Connection Log string Use a connection-specific log instead of the global log.
Connection Log Level string Logging level for the connection-specific log. (N=Use global level)
HL7 File Directory string The directory where received messages are stored.
Filename Prefix string Optional text to start message filenames with.
Extension string Extension for received message files.
Encoding string The sender and receiver must agree on the encoding: Default (single-byte) or UTF-8.
Port number The port to listen for connections on.
ACK MSH Template string Optional ACK MSH. If blank, use sender's MSH (see below).
ACK ERR Template string The template for ERR segments in rejected acknowledgements (see below).
Named Fields File string A Named Fields file to be used for validating incoming messages.
Validation Flags number What to validate: required fields, repetitions, max length, and/or data type.
Track Dupe Control IDsnumber Track the most recent # of MSH.10 message control IDs for duplicates. (0=Off, -1=Allow blank)
Persist Control IDs booleanPersist the tracked control IDs between service starts.
Connection Limit number Limit the number of simultaneous connections to this receiver.
Log Connection Info booleanLog the IPs and ports of the hosts that connect to the receiver.
Processing IDs string List the MSH.11 processing IDs accepted by this receiver. Blank=not checked.

A few things can cause a negative acknowledgement (NAK) on a received message, most of which are optional: the message fails to parse (hard fail), has a missing or duplicate message control ID, has an unaccepted processing ID, or fails data validation.

The message filenames will start with the optional prefix, a timestamp in yymmddhhnnsszzz format, a two-digit number to guarantee a unique filename, and the configured extension. The files are named this way to make it easy to process them in the order received. If you would like the files to be named differently, you can use HL7ScriptService to rename and/or move them based on any criteria you choose.

The ACK MSH Template on receivers is used to specify an MSH segment for the ACK messages. This will be updated with the current timestamp in MSH.7 and a time-based message control id in MSH.10. The sender's trigger event is also written to MSH.9.2. If left blank (recommended), the incoming message's MSH segment will be copied for use in the ACK message, reversing the sending/receiving application/facility fields (swap MSH.3/5 and MSH.4/6), replacing the timestamp and message control ID, and changing MSH.9.1 to ACK.

The ACK ERR Template on receivers is used to specify an ERR segment layout with replaceable parameters. The ACK message will contain one such ERR segment for each error encountered in the received message. If the template contains only a single field separator (i.e. has only ERR.1), multiple errors will be sent as repetitions of ERR.1 (the old HL7 2.3 behavior). If set to blank, no ERR segments will be sent at all.

Changes made to the Named Fields file while the service is running won't be picked up until the service is restarted.

Example HL7 2.7 ERR template (default): ERR||%sid^%q^%f^%c^%s|%code|E|||||%text

Example HL7 2.3 ERR template: ERR|%sid^%q^%f^%code&%text

ACK ERR Template Replacements
ValueReplaced With
%codeError code
%textError text
%sidSegment ID
%qSegment sequence
%fField index
%cComponent index
%sSubcomponent index
%rRepetition index

The Track Dupe Control IDs value indicates the number of most recently received MSH.10 message control IDs to keep in memory, with zero turning the feature off. If set to -1, blank message control IDs will be allowed (there are some senders out there that just can't follow specs). If a duplicate control ID is received, the message will be rejected. If the Persist option is checked, the IDs are saved to a file (ConnectionName_TrackDupes.txt) in the service directory at shutdown. Otherwise, the list of IDs is maintained only while the service is running.

Return to Top

Multiple Service Instances

HL7ScriptService and HL7TransmitterService can be configured to run multiple instances on a single server. A common use for this would be running both a Test and Production instance on the same server, possibly of different versions. The instructions are the same for either service.

Set up two (or more) separate application directories, each with its own copies of the executables. Run the configuration program in each directory to create the ini file. After configuring the regular settings, press the Service ID button. Enter a value that will uniquely identify the service running from each directory. Keep the value short and alphanumeric, like "Test" or "Prod".

The Service ID button will make sure your chosen ID is not already in use, and will automatically uninstall/reinstall the service as needed to change an existing ID. Any changes you may have made to the service startup type or logon account will be preserved for you. The Service ID is saved to the ini file.

When a ServiceID has been assigned, the configuration program will show the ID in square brackets in the Service Control area's status text:

HL7 Service ID

The service will appear in the Services management console with the ServiceID value appended to the base service name. If you had set up "Test" and "Prod" instances of HL7ScriptService, you would see the entries named HL7ScriptServiceTest and HL7ScriptServiceProd.

Each service can then be configured, started, stopped, or uninstalled independently of any others.

Each instance must have its own unique log filename(s); they must not try to share a common log file or they will fight over who gets to write to it.

Return to Top