This page contains my free utilities and tools for working with HL7 data.

The programs include an HL7 viewer/editor, a tool for analysis and transformation of messages that has its own easy-to-use scripting language, a TCP/IP transmitter/receiver service, and a bulk message sorting utility.

Please feel free to email me any questions or suggestions you may have. I'd love to hear from you! If anything starts to look like a common question, I'll make sure it is documented.

This is what I do for a living. I have spent a lot of time perfecting my HL7 classes in my spare time, so unlike my other freeware, I have not included the source code for these programs. I have placed the interface sections of my class source files down at the bottom of the page if you would like to get a better idea of their capabilities. If you are in need of some HL7 expertise or wish to commission a custom program, please contact me directly via email.

Table of Contents

Download

Latest Update: 2017-08-13

HL7Tools.zip
1.9MB, All HL7 programs and files mentioned on this page.
ReleaseNotes.txt
31K, The combined release notes for all the HL7 programs.

HL7Viewer

HL7Viewer

HL7Viewer is a utility for viewing and editing HL7 data in an expandable/collapsible tree view (no more counting pipe characters!). You can view messages from files containing one or many messages, messages pasted from the clipboard, or even search entire directories to load only messages meeting your specific criteria.

Features Include:

The latest features of note are Diff, Find in Files, and Anonymization.

A Diff is a comparison between two things (often text files) that shows where they differ by displaying them side-by-side. With HL7Viewer you can diff HL7 messages. Select the first message for the diff by right-clicking and choosing "Select for Diff". A little icon will appear next to the message to indicate the selection. Then right-click on another message and select "Diff with Selected". The differences are displayed in an easy-to-read grid. The results can be saved to a csv or text file.

The Find in Files feature will search a directory/wildcard of hl7 files (recursively if you wish) and load only those messages that match your criteria into the viewer. Much faster than loading everything and then filtering to remove the unwanted messages. Both Find in Files and message filtering use the HL7Script "IF" syntax to specify your matching criteria.

Anonymization allows you to quickly anonymize one or more messages based on an anonymizer definition you configure ahead of time. It persists data across the whole series of messages, so if MRN 12345 gets changed to TEST001, it gets changed to TEST001 in all the messages. A sample definition is included with the release, Generic.anon.ini. For more information, see the Anonymizer Definitions page.

Included with HL7Viewer is a text file called "HL7NamedFields.txt". There is an option within the program to show Named Fields rather than displaying each piece of data by its numeric position within a segment. For example, you may prefer to see MSH.MessageType.TriggerEvent instead of MSH.9.2. The provided field names are based off of the HL7 2.35 specifications. The list of fields is not exhaustive, just the ones I happen to encounter on a regular basis. Feel free to add your own (your custom Z-segments, for example) -- the file format should be pretty easy to understand and it includes comments. HL7Script will let you use named fields as well.

A recent addition to Named Fields is support for max length, optionality, repetitions, table, and ID values. Max length, optionality, repetitions, and data type can be used in any combination to Validate Data in one (right-click) or all (Messages menu) messages.

There is no installer for HL7Viewer. Just save it to your hard drive and create a shortcut to it. You can associate *.hl7 files with HL7Viewer if you wish, and it will open them when double-clicked. Program settings are stored in the registry under HKCU\Software\Ray Marron\HL7Viewer.

What you see here is all the documentation that exists for HL7Viewer, but every menu option shows a detailed hint in the status bar when hovered over. Hopefully, if you are familiar with HL7 it should be fairly intuitive. Please feel free to email any questions you may have.

Upgrade issue: If upgrading from a much older version (v3.x or prior), you may experience an "Index Out of Bounds" error when opening a message. Just delete the entire HKCU\Software\Ray Marron\HL7Viewer registry key. It will be recreated and the problem will go away.

Return to Top

HL7Script

HL7Script

HL7Script is for bulk-processing of messages for analysis or transformation. It has its own scripting language you can use to extract the information you need from the input messages. HL7Viewer tends to bog down when you start getting into the thousands of messages, but HL7Script has no problem processing hundreds of megabytes of data since it works on them one-at-a-time.

You can use HL7Script to modify messages or output a subset of messages that match your desired criteria. You can analyze large volumes of messages to get aggregate data like how many unique nursing unit/room combinations were seen in this time period, or how many patients had a particular set of diagnosis codes.

Detailed instructions on the script language used by HL7Script are included in the HL7Script Language Reference, along with numerous sample scripts.

There is no installer for HL7Script. Just copy it to your hard drive, create a shortcut and start using it. Program settings are stored in the registry under HKCU\Software\Ray Marron\HL7Script.

Return to Top

HL7ScriptService

HL7ScriptServiceConfig

HL7ScriptService is the Windows service version of the interactive HL7Script program. It will periodically poll a directory for files containing HL7 messages and process them with a script. Multiple such connections can be configured, each set to poll a different directory and use different scripts and settings. It includes a graphical configuration program to make it easy to set up, HL7ScriptServiceConfig.exe.

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

Detailed instructions on using HL7ScriptService are included in the HL7Script Language Reference.

Return to Top

HL7Script Language Reference

HL7Script Language Reference

Extensive documentation for HL7Script and HL7ScriptService is included in the page linked above.

Return to Top

HL7Transmitter

HL7TransmitterConfig

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.

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.

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. Only a few things can cause a negative acknowledgement (NAK): a message that fails to parse, a missing or duplicate message control ID (optional), or a message that fails data validation (optional). 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.

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.


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.
Schedule specialDetermine when the transmitter will connect to the remote host. See below.
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.
Port number The port the remote host is accepting connections on.
Remote Address string The IP address of the remote host.
Transmit Interval number Number of seconds between input directory polling.
Max Files/Interval number Limits the number of files processed per interval to keep the service responsive.
ACK Timeout number Number of seconds to wait for an ACK message before giving up.
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.
Connection Log string Use a connection-specific log instead of the global log.
Connection Log Levelstring Logging level for the connection-specific log. (N=Use global level)

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.
Schedule specialDetermine when the receiver will accept connections. See below.
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.
Port number The port to listen for connections on.
ACK MSH Template string Optional ACK MSH. If blank, use sender's MSH (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 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.
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 Transmitter Service Global Settings
Setting NameTypeNotes
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)

To install the service, use "HL7TransmitterService /install" in a command prompt that was started using "Run as Administrator". To uninstall, use /uninstall. The configuration program can also install and control the service when Run as Administrator. It appears in the Service Control Manager as "HL7TransmitterService".

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.

Settings are stored in HL7TransmitterService.ini in the same directory as the service executable. 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.

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.

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.1. If left blank, 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) and replacing the timestamp, message control ID, and changing MSH.9.1 to ACK.

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.

The log file 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.

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.

Return to Top

HL7Sort

HL7Sort is a command-line utility that will read an input file or directory full of HL7 messages and write them to an output file in a user-selected sorted order but otherwise unchanged. HL7Viewer is fine for sorting a few hundred messages, but HL7Sort can work on very large files.

To see help for the program, just run it without any arguments.

Return to Top

HL7 Classes

These are the actual HL7 classes used to build these programs, but only the interface sections. These are here to give you an idea of the flexibility and power of the classes should you need some custom work done or are considering licensing the classes for yourself. Please contact me directly by email with any questions.

llHL7Msg.txt
llHL7Script.txt

Return to Top

License

The works on this page by Ray Marron are licensed under specific terms found in license.txt distributed as part of hl7tools.zip.