The HL7Forge User Guide

01The layout

One window, five working areas. Templates live on the left. Connection settings and the activity log share the right column, so your network state and traffic sit together. Both side panels slide out of the way when you need room, and every divider drags to resize.

02Create a message

You rarely need to write HL7 from scratch. Pick a template from the sidebar (ADT, ORU, ORM, SIU, MDM, MFN, DFT, VXU, RDE, OML, REF and ACK are all included) and a valid message opens in a new tab, ready to edit or send. You can also save any message of your own as a reusable template.

03Connections

The connection panel sits above the activity log. Enter a host and port, pick a transport, and you are ready to send. Save the combination as a named endpoint and it comes back on every launch, shared with everyone using the same install.

1. Enter the Host / IP and Port of the system you are testing against.
2. Pick a transport: MLLP for standard HL7, MLLP over TLS for encrypted links, or raw TCP.
3. Click Test Connection. The titlebar LED turns green when the listener answers.
4. Click Save, give it a name, and the endpoint appears in the dropdown from then on.

TLS

Many hospitals now require encrypted HL7 links. Choose MLLP over TLS as the transport to send encrypted, with an option to accept self-signed certificates for test systems. The receiver can terminate TLS too: tick TLS listener and point it at your PEM certificate and key files.

04Send & receive

Click Send Current and watch the round trip in the activity log: the outbound message, the returning ACK, and how long it took. Start the listener and inbound messages appear in the same log as they arrive.

05Working with files

Load whole HL7 files and step through the messages one at a time, or send the entire batch in one pass. Large files stream in with a progress bar, and files carrying embedded documents (base64 PDFs and RTFs, even tens of megabytes) open without trouble.

06The editing views

Raw HL7 when you want speed, Field Editor when you want precision, Parsed View when you just want to read. They stay in sync: click a field in one and the others follow.

Raw HL7

Click anywhere in the message and the status bar names the exact field under the cursor. Hold the mouse over a field and a tooltip shows its ID, name and value, with the plain meaning for coded fields.

Field Editor

Every field on its own row, labelled, with a length counter that warns when a value goes past the HL7 maximum. Fields with components (a PID.5 name, for example) expand into per-component rows.

07Split screen

Split the editor into two panes and give each one its own view tab. Raw HL7 on top with the Field Editor underneath is the usual pairing. Type in either pane and the other updates as you go. Drag the divider to resize.

08Find & replace

Press Ctrl+F or click Find in the toolbar. Matches highlight as you type, with Prev and Next to walk through them. Open the replace row to swap values in the current message, across every message in the loaded file, or only inside one segment type.

09Validate

One click checks required fields, coded values, timestamp formats, segment names and message structure. Each problem is listed and highlighted red at the spot where it lives.

10Anonymize

Strip patient data before sharing a message with a vendor or colleague. Choose which fields to clear or randomise (names, MRNs, dates of birth, addresses, phone numbers, next of kin, doctors), give fixed values where you need them, and save the combination as a preset. Changed fields flash briefly so you can see exactly what was touched.

11Explain & FHIR

Explain opens a plain-English window for the current message: what it is, who sent it, the patient, the visit, and the results with abnormal values flagged. Useful when you need to walk a non-HL7 person through a message.

FHIR view

The FHIR button next to Explain shows the same message as a FHIR R4 bundle: Patient, Encounter, Observations, DiagnosticReport, allergies and diagnoses, mapped from the v2 segments. It is read-only, with a copy button, and is meant for review and vendor conversations rather than production conversion.

12Timeline

The Timeline tab groups a loaded file by patient and lays each patient's messages out in time order: admit, transfer, results, discharge. Click any event to jump straight to that message. The search box filters by patient name or MRN, which is the quick way to find one patient in a large file. It reads PID.3 for the patient and MSH.7 for the order of events.

13Compare

Put two messages side by side and see the differences field by field. Paste into slot A and B (or send messages there from the right-click menu), and the table on the right lists every segment that differs, with the A and B values in adjacent columns. The header counts the differences and a checkbox shows or hides identical fields.

14Query

Search every loaded message by field value. Conditions can be combined with AND, and the matches land in a table you can open as a new batch or export to CSV.

15Statistics & gap analysis

The Statistics tab profiles a whole batch: which fields carry data, what values appear, and how often. The Gap Report starts with a message-type breakdown, then walks the segments in message order showing every defined field's fill rate, including fields that never carry a value at all.

16Routing rules

Routing turns HL7Forge into a small interface engine. Messages are checked against your rules top to bottom, first match wins, and the matching rule forwards to an MLLP endpoint, logs, or drops the message.

17CSV generator

When you need a batch of realistic test messages, build them from a spreadsheet. One CSV row becomes one message: pick a base template, load the file, map each column to an HL7 field path, and generate.

A CSV for ten test admissions looks like this (the first rows shown):

Name your headers as field paths, like above, and the mapping fills itself in the moment the file loads. Any other header works too; you just type the target path yourself.

18Load testing

The Load Test window sends the current message repeatedly at a target rate, each copy with a fresh control ID, and measures the ACK round trip. You get live counts, achieved throughput, and latency percentiles as it runs.

19Transforms & auto-responder

Two quiet workhorses. Transforms rewrite fields on every outgoing message (swap the sending facility, stamp a test flag) without touching your files on disk. The auto-responder answers inbound messages with rule-based ACKs so you can simulate the system on the other end, including NACKs and slow responses.

20Activity log

Everything that happens lands here with a timestamp. Click a row to see the full sent message and its ACK. The ↺ button resends a past message through the current connection, and Export writes the whole log to a text file for a ticket or a handover.

21Workspaces

A workspace file captures your whole session: every open tab with its messages, plus the connection settings. Save one at the end of a piece of testing and reopen it days later exactly where you left off, or hand the file to a colleague so they start from your setup.

1. Click 🗂 Workspace in the titlebar and choose Save Workspace. Everything open goes into one .hl7ws file.
2. To restore, choose Open Workspace and pick the file. HL7Forge confirms before replacing your current tabs.

22Themes & text size

Nine themes from deep dark to bright light, picked from the dropdown in the titlebar and applied instantly. Settings adds an intensity slider and three text sizes. Try the dropdown here:

23Shortcuts & tips