HL7Forge The HL7Forge User Guide
Every feature in the app, demonstrated live. Each animation below is a faithful recreation of the real interface — what you see here is what you get.
01The layout
One window, five working areas. The side panels collapse with a click (and slide smoothly out of the way), and every divider drags to resize.
02Create a message
Never start from a blank page. Pick any of the built-in templates — ADT, ORU, ORM, SIU, MDM, MFN, DFT, VXU, RDE, OML, REF, ACK — and a realistic, valid message opens in a new tab, ready to edit or send.
03Endpoints & connection
Point HL7Forge at any listener: hostname or IP, port, and transport (MLLP or raw TCP). Test the connection, then save it as a named endpoint you can recall from the dropdown.
- Enter Host / IP and Port in the sidebar.
- Pick a transport — MLLP (standard HL7) or raw TCP.
- Click Test Connection — the titlebar LED turns green on success.
- Type a name and Save — the endpoint is now one click away, on every machine restart.
04Send & receive
Send the current message with one click and watch the full round trip in the activity log — outbound message, returning ACK, and timing. Flip on the listener and inbound messages appear the same way.
05Working with files
Load whole HL7 files — thousands of messages stream in with progress, and files with embedded documents (base64 PDFs/RTFs, even tens of MB) open safely. Step through messages one at a time, or send the entire batch.
06The three editing views
Raw HL7 for speed, Field Editor for precision, Parsed View for reading. All three stay in sync — click a field in one and the others follow.
Raw HL7 — click to identify, hover to inspect
Click anywhere and the status bar names the exact field. Hovering shows a tooltip with the field ID, name, value, and — for coded fields — the plain-English meaning from the HL7 tables.
= "F" → Female
Field Editor — every field, labelled and editable
07Split screen
Split the editor horizontally and give each pane its own view tab — Raw HL7 on top, Field Editor below is the classic combo. Edits in either pane update the other instantly. Drag the divider to resize.
| Field | Name | Value |
|---|
08Find & replace
Find highlights every match as you type; Replace works on the current message, the whole loaded file, or — surgical option — only within one segment type across every message in the batch.
09Validate
One click checks required fields, coded values, timestamp formats, segment names, and cross-segment structure. Problems are listed and highlighted red, right where they live in the raw view. Add your own rules — mandatory fields, patterns, lengths — for vendor-specific profiles.
10Anonymize
Strip PHI before sharing a message with a vendor or colleague: names, MRNs, dates of birth, addresses, phone numbers, next-of-kin, attending doctors. Choose exactly which fields, supply fixed values or let HL7Forge randomize, and save the combination as a preset. Changed fields flash and fade so you can see precisely what was touched.
11Explain
Hand any message to a non-HL7 person. Explain opens a plain-English window: what the message is, who sent it, the patient, the visit, and every result — with abnormal values flagged.
12Compare
Put two messages side by side and see exactly what differs, line by line. Send any message to slot A or B from its right-click menu, or paste directly — perfect for "why did this one fail when that one worked?".
13Query
Search every loaded message by field value — equals, contains, comparisons, combined with AND. Matches land in a table you can open as a new batch or export to CSV.
| # | MSH.9 | PID.5 — Patient | OBX.3 — Test | OBX.5 | OBX.8 |
|---|
14Statistics & gap analysis
The Statistics tab profiles a whole batch: which fields are used, with what values, how often. The Gap Report goes further — it starts with a message-type breakdown, then walks the segments in message order showing every defined field's fill rate, including the ones that are never populated.
15Routing rules
Turn HL7Forge into a mini interface engine. Inbound messages are evaluated against your rules top-to-bottom — first match wins — and forwarded to any MLLP endpoint, logged, or dropped.
| # | On | Name | Condition | Action | Destination |
|---|
16CSV generator
Need 500 test patients? Point the CSV generator at a spreadsheet — one row per message, columns mapped to HL7 fields — pick a base template, and generate the whole batch in seconds.
17Load testing
Rate-based load with live results: pick messages per second and duration, and watch throughput, ACK counts, and latency percentiles update as the run progresses.
18Transforms & auto-responder
Two quiet workhorses. Transforms rewrite fields on every outgoing message — swap the sending facility, stamp a test flag — without touching your saved files. The auto-responder answers inbound messages with rule-based ACKs (accept ADTs, reject ORMs, delay responses) to simulate the system on the other end.
19Activity log
Everything that happens lands here with a timestamp. Click any row for the full sent message and ACK; resend a past message with ↺; export the lot to a text file for a ticket or handover.
| Time | Dir | Message | ACK |
|---|
20Themes & text size
Nine themes from deep dark to bright light, an intensity slider to push any theme brighter or more vivid, and three text sizes. Watch it live:
21Shortcuts & tips
| Ctrl+F | Find (and replace) in the current message or batch |
| Ctrl+Z / Ctrl+Y | Undo / redo edits |
| Click in Raw view | Identify the field under the cursor in the status bar — and highlight it in the other views |
| Hover in Raw view | Tooltip with field name, value, and coded-value meaning |
| Right-click in Raw view | Copy field/segment, send to Compare A/B, filter Statistics by this value |
| Drag panel edges | Resize sidebar, activity log, and split panes; ‹‹ / ›› buttons collapse them entirely |