The HL7 2.x format parses and emits HL7 2.x messages (MSH, PID, OBR, OBX, …) in either the standard pipe-delimited ER7 encoding or HL7 XML. This article is the parameter reference. For the end-to-end usage walkthrough — transports (MLLP, HTTP), reformat patterns, ACK / NACK handling — see Working with HL7. For scripting against the HL7 object model, see Create HL7 messages using scripting.
When should I use this format?
Use the HL7 2.x format for any version of HL7 2.x — lab orders (ORM), lab results (ORU), ADT (admit / discharge / transfer), pharmacy, claims, scheduling, and so on. For HL7 FHIR (the modern resource-based HL7 standard), use the HL7 FHIR format instead.
Create an HL7 2.x format
- Open Connections and select the Formats tab.
- Click +, search for HL7, and select HL7 2.x (in the HL7 group).
- Set HL7 Version and Type of Encoding (required) and any other parameters you need.
HL7 parameters
| Parameter |
Default |
What it does |
|
HL7 Version (required) |
Any |
The HL7 2.x version: 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1, 2.6, 2.7, 2.8, 2.8.1, 2.8.2, or Any. Use Any when the version varies and the parser should read MSH-12 from the message itself. |
|
Type of Encoding (required) |
ER7 |
ER7 is the standard HL7 pipe-delimited format (MSH, PID, … with |, ^, &, ~, \ delimiters). XML is HL7's XML encoding. ER7 is the right choice for almost all production exchanges. |
| Validate |
off |
Validate the HL7 message against the schema before passing it to the connector. Off by default; many production senders emit messages that pass real-world validators but fail strict schema checks — enable only when you know your partner is compliant. |
| Datatype if OBX2 Missing |
(blank) |
Default OBX data type code (ST, NM, FT, TX, …) when OBX-2 is missing from the inbound message. Useful for accepting partners that drop OBX-2 even though the standard requires it. |
| Datatype if OBX2 Invalid |
(blank) |
Default OBX data type code when OBX-2 has an unrecognized value. |
| Encode First Segment |
true |
When encoding a group whose first segment is required but no data has been provided for it, generate an empty segment anyway. Turn off only when a partner refuses placeholder segments. |
| Escape Subcomponent Delimiter |
false |
Ignore subcomponent delimiters (&) inside OBX-5. Helpful when the value contains literal ampersands that aren't meant as HL7 delimiters. |
| Enforce Encoding For |
(blank) |
Comma-separated list of segments / fields where the parser will enforce encoding even if the field is empty. Useful for partners that require placeholder segments. |
| Remove Encoding For |
(blank) |
Comma-separated list of segments / fields where the parser will strip encoding. |
| Namespace |
urn:hl7-org:v2xml |
XML namespace for HL7 XML encoding. Override only when a partner uses a non-standard namespace. |
| Template |
(blank) |
When the actual input file isn't available during flow design, the template populates column names so mapping can still be built. Example: first,last,dob. |
| Parameter |
What it does |
| Preprocessor |
JavaScript that modifies the raw HL7 message before the parser sees it. See Preprocessor for the available variables and the typical pattern. Useful for fixing partner-specific quirks (stray characters, line-ending differences, MSH header tweaks) that aren't worth a full transformation step. |
Parsing options
Date / time / encoding / null-handling settings shared with most other formats in Etlworks.
| Parameter |
Default |
What it does |
| Date and Time Format |
MM/dd/yyyy HH:mm:ss |
Format for date+time output (Java SimpleDateFormat pattern). HL7 timestamps in TS / DTM fields are normalized to this format on read. |
| Date Format |
MM/dd/yyyy |
Format for date-only output. |
| Time Format |
HH:mm:ss |
Format for time-only output. |
| Parse Dates |
off |
When the input doesn't match the configured formats, attempt automatic parsing. Useful when partners send dates in mixed formats. |
| Trim Strings |
off |
Strip leading / trailing whitespace from string values. |
| Convert 'null' to null when reading |
off |
Treat the literal string 'null' (case-sensitive) as a SQL null. |
| Convert empty string to null when reading |
false |
Treat empty strings as nulls. |
| Value for null when reading |
(blank) |
Comma-separated list of string tokens (e.g., NULL, n/a, -) interpreted as null when read. |
| Encoding |
UTF-8 |
Character encoding for the input. HL7 message bodies usually use UTF-8; some legacy interfaces use ISO-8859-1. |
Overrides
| Parameter |
What it does |
| Function to calculate Filename |
JavaScript that rewrites the file name when reading or creating an HL7 file. The input is fileName; assign the result to value. Useful for dropping prefixes, appending dates, normalizing partner-specific naming conventions. |
| Function to calculate Field Name |
JavaScript that rewrites column names produced by the parser. The input is name; assign the result to value. |
HL7 object model and scripting
Parsed HL7 2.x messages are exposed to JavaScript / Python flows as HAPI HL7v2 Java objects through dataSet.getActualData() / setActualData(). For the full scripting reference — the HAPI library, package layout per HL7 version, common patterns (clone, DeepCopy, iterate, insert / remove segments), and two worked examples drawn from real clinical interfaces — see Create HL7 messages using scripting.