Working with HL7

HL7 is the dominant data exchange standard in healthcare. Etlworks supports both HL7 2.x (the long-standing pipe-and-hat message format) and HL7 FHIR (the modern resource-oriented standard) end to end: parse, transform, generate, send and receive over MLLP and HTTP. This article is the single reference for HL7 in Etlworks.

For the dialect-agnostic EDI umbrella, see Get started with EDI documents.

HL7 versions and what each one is

What can you do with HL7 in Etlworks?

The HL7 format

An HL7 format defines how Etlworks parses or builds HL7 messages. Create one in Connections → Formats and pick HL7 2.x or HL7 FHIR.

Key settings on the HL7 2.x format:

Read HL7

To parse HL7 messages and load the data into a database, file, or API, set the HL7 format on the source side.

1. Create the source connection that holds (or receives) the HL7 messages — file storage, an MLLP listener, or an HTTP listener.
2. Create an HL7 format (see The HL7 format above).
3. Create the destination connection (database, file, API, …).
4. Create the matching flow type — HL7 to database, HL7 to file, HL7 to API, HL7 to HL7.
5. Add a transformation. Set FROM to the source connection / HL7 format / message file or topic.
6. Click MAPPING to open the nested mapping editor. The source tree shows HL7 segments (MSH, PID, ORC, …) and fields. Drag onto the destination structure.
7. Save and execute.

Nested vs. flat mapping

• Nested mapping preserves the HL7 hierarchy. Use it when the destination is JSON / XML / nested-friendly, or when you want to load multiple segments into linked tables in one pass.
• Flat mapping lets you target one segment type at a time — e.g., load every OBX observation across a batch of messages into one observations table. Set a Source query under MAPPING > Source query like SELECT * FROM OBX.

Write HL7

To generate an HL7 message from a source dataset, set the HL7 format on the destination side. The source can be a database query, a file, an API response, or another HL7 message. Etlworks emits a valid HL7 message with correctly-formed MSH, delimiters, and segment hierarchy.

1. Create the source connection.
2. Create an HL7 format for the target HL7 message.
3. Create the destination connection — file storage, HL7 MLLP sender, or HTTP.
4. Create a flow whose destination matches (e.g., database to HL7, file to HL7, HL7 to HL7).
5. Add a transformation. Map source fields onto HL7 segments using the nested mapping editor — the destination tree shows MSH, PID, etc., with the correct field cardinality.
6. Save and execute.

For per-record calculations, conditional segments, or HL7 logic that doesn't fit mapping, see Scripting with the HL7 object model below.

MLLP transport

MLLP (Minimal Lower Layer Protocol) is the transport HL7 systems use over plain TCP. Etlworks ships dedicated MLLP sender and listener connection types.

Send HL7 over MLLP

1. Create an HL7 MLLP Sender connection. Configure the partner host / port and any TLS settings.
2. Create the HL7 format you'll emit.
3. Create the source connection.
4. Create a flow that matches the source (e.g., file to HL7, HL7 to HL7).
5. Set TO Connection to the MLLP sender. Set TO Format to the HL7 format.
6. Map source to HL7 segments.
7. Save and execute.

HTTP transport

Some modern HL7 deployments — especially FHIR — use HTTP rather than MLLP. The standard HTTP connector and HTTP listener work with HL7 messages: set the HL7 format on the relevant side of the flow, otherwise the configuration is the same as any HTTP flow.

Send HL7 over HTTP

1. Create an HTTP API connection pointed at the receiver endpoint.
2. Create the HL7 format you'll emit.
3. Create the source connection.
4. Create a flow that targets HTTP as the destination (e.g., file to web service).
5. Set TO Connection to the HTTP connection, TO Format to HL7.
6. Map source to HL7 segments.

Receive HL7 over HTTP

1. Create an HTTP listener pointed at a URL path on your Etlworks instance.
2. Create the HL7 format for inbound.
3. Create the destination connection.
4. Create a flow where the source is the HTTP listener with the HL7 format and the destination is the downstream system.

Scripting with the HL7 object model

When HL7 messages are parsed or created, Etlworks stores them as HL7 objects — instances of the version-specific classes shipped by the HAPI HL7v2 library (ca.uhn.hl7v2). From JavaScript / Python flows you can reach into the object model directly through two methods on com.toolsverse.etl.common.DataSet:

Use this hook for transformations that don't fit nested mapping: branching on field values, generating multiple output messages from one input, or reformatting deeply nested OBX repetitions in code. Day-to-day HL7 work doesn't need the object model — nested mapping covers most cases.

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.

Notes and limitations

• FHIR — treated as structured JSON. Use the JSON nested-mapping path; the HTTP listener / connector handles FHIR RESTful endpoints.
• MLLP TLS is supported on both sender and listener. The listener's port is the most common failure point; verify firewall rules on-premise or open with support on cloud.
• ACK / NACK for MLLP listeners is generated automatically on receipt of each message; configure the application acknowledgment behavior on the listener connection.
• HL7 object model versions follow the HL7 version on the format — mixing versions across a single flow is allowed (e.g., parse 2.3, emit 2.5) but the mapping must convert between the two structures explicitly.

Related articles

• Get started with EDI documents — the dialect-agnostic umbrella.
• Working with X12 — X12 and EDIFACT, the non-healthcare EDI dialects.
• Nested mapping — the mapping mechanism HL7 work uses end-to-end.
• Working with the Mapping Editor.