Read HL7 v2 messages in plain language, right inside Notepad++.
Put the caret anywhere in a message and HL7Lens tells you where you are, what the field is called, its data type, its value and what that value means.
- Why HL7Lens
- Install
- Features
- Compare two messages
- Version-aware field names
- Custom segments (Z-segments)
- Command line
- Build from source
- Signature
- Privacy
- Questions and feedback
- Support development
- License
Most people who work with HL7 v2 interfaces read the messages in Notepad++. A raw message is a wall of
pipes and carets: PID|1||123456^^^HOSP^MR~77^^^OTHER^PI||DOE^JANE^M||19800101|F. HL7Lens turns that
into something you can read without counting separators, and it never sends a byte anywhere.
- Press Windows key + R to open the Run box.
- Paste this line and press Enter:
powershell -c "irm https://raw.githubusercontent.com/Subzero121800/HL7Lens/main/install.ps1|iex"
A window opens for a few seconds and closes by itself. A pop-up tells you what happened, and Notepad++ opens with a short getting-started guide and a sample message: press Ctrl+Alt+H there. If Notepad++ is open, the installer offers to close it first (it asks about any unsaved work). It never asks for administrator rights.
On most managed PCs Notepad++ is installed under C:\Program Files, and Windows only lets an administrator add
files there. That is a Windows rule, and Notepad++ only loads plugins from its own plugins folder.
Use the same Run box line. When the plugins folder is protected, the installer changes nothing in Notepad++ and does
not ask for admin rights. It downloads and checks HL7Lens and saves it in your Downloads folder as
HL7Lens-Plugin, then opens that folder and the instructions:
HL7Lens: the ready-to-copy plugin folderHOW-TO-INSTALL.txt: where the folder goes, and for IT the file's SHA-256, the signer and what the plugin does (offline, no network connections, no telemetry)
If you can approve admin prompts, copy the HL7Lens folder into Notepad++'s plugins folder yourself. Otherwise
attach HOW-TO-INSTALL.txt to an IT ticket; copying one folder is a two-minute job. IT can also deploy it to many
PCs silently (as administrator or SYSTEM; no pop-ups in that case):
powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 -ZipPath <release zip>.
If your agency blocks PowerShell entirely, use Manual below and send IT the x64\HL7Lens folder from the zip.
Close Notepad++, open PowerShell and run:
irm https://raw.githubusercontent.com/Subzero121800/HL7Lens/main/install.ps1 | iexThe installer finds Notepad++, picks the 64-bit or 32-bit build to match it, downloads the latest
release, checks its SHA-256 checksum and that the DLL is signed by the author, then copies it to
plugins\HL7Lens\ when that folder is writable, or to Downloads\HL7Lens-Plugin with instructions when it is not.
| Option | What it does |
|---|---|
-NppPath D:\Tools\npp |
Portable Notepad++ (the folder that holds notepad++.exe) |
-Version 1.1.0 |
A specific release instead of the latest |
-ZipPath .\HL7Lens_NotepadPlusPlus_v1.1.0.zip |
Install from a zip you already downloaded |
-Admin |
Copy into a protected plugins folder (Windows asks for admin approval) |
-Quiet |
No pop-ups, and do not open Notepad++ afterwards |
-Force |
Close a running Notepad++ first, without asking |
-Uninstall |
Remove the plugin (settings stay in plugins\Config\HL7Lens) |
To pass options, download the script first: irm https://raw.githubusercontent.com/Subzero121800/HL7Lens/main/install.ps1 -OutFile install.ps1, then .\install.ps1 -NppPath ....
Unzip the release, close Notepad++ and double-click install.cmd. It installs the files beside it (no
download) and runs PowerShell with -ExecutionPolicy Bypass for that one run, so Windows' default
"running scripts is disabled on this system" policy does not block it. Options work here too:
install.cmd -NppPath D:\Tools\npp, install.cmd -Uninstall.
- Download
HL7Lens_NotepadPlusPlus_vX.Y.Z.zipfrom Releases. - Check your Notepad++ under ? > About Notepad++ (64-bit or 32-bit).
- Drag
x64\HL7Lens(orx86\HL7Lens) into Notepad++'spluginsfolder, so you end up with...\plugins\HL7Lens\HL7Lens.dll. - Start Notepad++ and press Ctrl+Alt+H.
Optional: Plugins > HL7Lens > Install HL7 v2 syntax colors, then restart Notepad++ once; .hl7 files then color automatically.
Decoder panel (Ctrl+Alt+H, docks on the right)
- Live readout of the field under the caret: path (
PID-3(2).1), field and component names, data type, repetition (Repetition 2 of 3), unescaped value and plain-language meaning. - Message tree: summary, then segment > field > repetition > component > subcomponent. Click a node to select it in the editor; move the caret and the tree follows.
- Meanings: names (
DOE, JANE M), addresses, phone numbers, timestamps with time zone and age, code tables (sex, patient class, result status, abnormal flags ...), coding systems (LOINC, SNOMED CT ...) and message types (ORU^R01 = Unsolicited observation result). - Validation: missing MSH-9/10/12, bad segment IDs, invalid timestamps, non-numeric NM values, missing required segments, version drift, wrapped lines, and fields the declared version does not define.
- Version and ELR checks: declared version against the features actually used, backward-compatible fields, and electronic lab reporting readiness.
- Filter, Hide empty, Expand all / Collapse all.
Navigation
| Command | Shortcut |
|---|---|
Go to field path (PID-3.1, OBX[2]-5, PID-3(2).4) |
Ctrl+Alt+G |
| Next / previous field (each repetition is a stop) | Ctrl+Alt+Right / Left |
| Next / previous message | Ctrl+Alt+PgDn / PgUp |
| Mark a field in every segment, list a field across every message | menu |
Tools (Plugins > HL7Lens): decoded report, JSON export, ACK builder (AA/AE/AR), de-identified copy,
repair (MLLP framing, blank and wrapped lines, smart quotes; undoable), escape and unescape
(\F\ \S\ \T\ \R\ \E\ \.br\ \Xhh\), segment separators to CRLF or CR.
Handles CR, LF and CRLF separators, many messages per file (each with its own MSH separators), FHS/BHS batches, custom encoding characters, MLLP framing and Z-segments.
Interface work is mostly "why did this one fail when that one worked?"
- Compare message at caret with another message in this file...
- Compare message at caret with the clipboard
- Compare message at caret with the other view (open both files side by side: right-click a tab > Move Document > Move to Other View)
The report opens in a new tab:
Summary: 3 value difference(s), 0 segment(s) only in A, 1 segment(s) only in B, 4 segment(s) matched.
DIFFERENT VALUES
PID-5.2 Patient Name > Given Name
A: JANE
B: JOHN
OBR-44(2) Procedure Code
A: 26543
B: (empty)
SEGMENTS ONLY IN B
NTE Notes and Comments NTE|1||Hemolyzed
VALIDATION FINDINGS THAT DIFFER
only A warn OBR-44 Procedure Code repeats 3 times, but HL7 v2.5.1 does not allow repetitions here.
EXPECTED TO DIFFER (timestamp / control ID)
MSH-7 ... MSH-10 ...
Segments are aligned by ID (longest common subsequence), so one inserted NTE does not make every later segment look different. Values are compared down to repetition and component.
HL7 v2.3 and v2.5.1 differ in real ways, and a decoder hard-wired to one version quietly mislabels fields. HL7Lens reads MSH-12 and uses that version's definitions for field names, data types and repetition rules: 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1, 2.6, 2.7 and 2.7.1 (later versions use 2.7.1; anything in between uses the closest earlier version).
| v2.3 | v2.5.1 | v2.7.1 | |
|---|---|---|---|
| OBR fields | 43 | 50 | 54 |
| OBR-4 type | CE | CE | CWE |
| OBR-44 | not defined (warned) | Procedure Code [CE] | Procedure Code [CNE] |
The tree summary names the definitions in use, and Validation flags populated fields the version does not define and fields that repeat where the version allows one value.
Plugins > HL7Lens > Define custom segments... opens settings.ini with a commented example. Define each
segment once and the tree, readout, validation and compare all use the names:
[ZCT]
Description=Lab contact (site-specific)
1=Set ID|SI
2=Contact Role|CWE
3=Contact Name|XPN|repeats
4=Contact Phone|XTN|repeatsn=Name|DATATYPE, plus |repeats for a repeating field. Components come from the data type, so ZCT-3.1
reads Contact Name > Family Name. Changes apply as soon as you save the file.
tools\hl7_cli.exe (and hl7_cli_x86.exe) runs the same decoder outside the editor:
hl7_cli pretty file.hl7 hl7_cli validate file.hl7 hl7_cli vcheck file.hl7
hl7_cli json file.hl7 hl7_cli deid file.hl7 hl7_cli repair file.hl7
hl7_cli diff a.hl7 b.hl7 hl7_cli ack file.hl7 AA "text"
hl7_cli resolve file.hl7 PID-5.2 hl7_cli locate file.hl7 <offset>
Use - instead of a file name to read standard input.
HL7Lens is C++17, cross-compiled with mingw-w64 and statically linked (no runtime DLLs).
sudo apt install g++-mingw-w64-x86-64 g++-mingw-w64-i686 python3
make test # native core + test suite
make x64 # build/x64/HL7Lens.dll + hl7_cli.exe
make x86 # build/x86/HL7Lens.dll + hl7_cli.exe
make data # regenerate the dictionaries from tools/*.jsonThe plugin has a built-in self-test: start Notepad++ with HL7LENS_SELFTEST=<report file> and it runs
55 checks against the live editor (panel, tree, caret tracking, arrow keys, every command, versions,
custom segments, compare, About box) and writes the report.
| Path | Contents |
|---|---|
src/hl7.cpp |
Parser, decoder, validation, compare, repair, ACK, de-identification |
src/dict.cpp |
Dictionary lookups (custom > message version > base) |
src/plugin.cpp |
Notepad++ plugin: panel, commands, self-test |
src/cli.cpp |
Command-line tool |
tools/ |
Dictionary data and generators |
tests/ |
Test suite and message fixtures |
npphdr/ |
Notepad++ plugin interface headers (GPL v3) |
Release binaries are Authenticode-signed (SHA-256, RFC 3161 timestamped) with the author's own code-signing certificate:
- Subject:
CN=Joseph C McGinty Jr. - SHA-1 thumbprint:
52C94A9DFEE33D25429354D2A7837EC227B665F4 - SHA-256 fingerprint:
C3:ED:17:2F:44:64:50:D6:CD:F5:8B:72:57:48:3D:58:A7:64:1B:73:42:3D:57:8B:EF:8C:0F:E5:4C:92:45:5D
Check it under the DLL's Properties > Digital Signatures. The certificate is self-issued, so Windows
reports it as untrusted until you choose to trust it. The public certificate is in
signing/; the installer refuses any DLL that is not signed by it.
HL7Lens works entirely offline. It reads only the text open in the editor, sends nothing over any network and stores no message content. De-identification is a best-effort aid: always review a copy before you share it. Never attach real patient data to an issue.
- Questions and ideas: Discussions
- Bugs: Issues (attach a synthetic message that shows the problem)
- Security problems: report privately, see SECURITY.md
HL7Lens is free and always will be. If it saves you time, you can support its development:
Copyright (c) 2026 Joseph C McGinty Jr.
HL7Lens is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Third-party components are listed in NOTICE.md.
HL7 and Health Level Seven are registered trademarks of Health Level Seven International. HL7Lens is an independent project and is not affiliated with, endorsed by or sponsored by HL7 International or any software vendor. Notepad++ is a trademark of its respective owner.