How to receive HL7 v2 messages in Python

Over MLLP - the Minimal Lower Layer Protocol, a thin TCP framing that hospital systems have used for decades. Each message arrives wrapped in a start byte and an end sequence on a TCP port, and the receiver must reply with an HL7 acknowledgment, an ACK message.

A working receiver therefore needs three parts - an MLLP listener that accepts TCP connections and unwraps frames, a parser that turns the pipe-delimited ER7 payload into something a program can read, and an ACK responder that tells the sender the message was accepted or rejected.

Three main options cover different amounts of the job. python-hl7 and hl7apy are parsing libraries with basic MLLP pieces, Zato is an integration platform where MLLP channels are production infrastructure with routing, security and multi-server scaling around them.

For a script that parses a file of messages, a parsing library is enough. For a listener that hospital systems connect to around the clock, the production concerns - acknowledgments, retransmissions, routing, monitoring, high availability - are most of the work, and that is what a platform provides.

Create an MLLP channel in the Dashboard - name, TCP port and the service that will handle each message. The channel unwraps the MLLP framing, parses the ER7 payload into a typed message object, invokes the service and sends the acknowledgment back - an AA when the service completes, an AE with error details when it raises an exception.

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class LabResultListener(Service):
    name = 'demo.hl7.lab-result-listener'

    def handle(self) -> 'None':

        # The channel already parsed the raw ER7 bytes ..
        msg = self.request.input

        # .. read what the integration needs ..
        control_id = msg.msh.message_control_id
        message_type = msg.get('MSH.9.1')

        # .. convert the whole message to JSON for downstream systems ..
        as_json = msg.to_json()

        self.logger.info('Received %s (%s), %d bytes of JSON',
            control_id, message_type, len(as_json))

        # .. returning nothing means Zato replies with an AA acknowledgment.

Send a test message to localhost:11553 with any MLLP client and the channel returns the acknowledgment as the response.

Messages parse into typed objects - every segment of the v2.9 specification is a Python class and every field has a semantic name, as documented in field access and path expressions.

from zato.hl7v2 import parse_hl7

raw = (
    'MSH|^~\\&|SENDER|FACILITY|RECEIVER|FAC|20260315||ADT^A01^ADT_A01|CTL001|P|2.9\r'
    'EVN|A01|20260315\r'
    'PID|1||12345^^^HOSP^MR||SMITH^JOHN^A||19800115|M\r'
    'PV1|1|I|WARD^101^BED1\r'
)

message = parse_hl7(raw, validate=False)

# Semantic names ..
family_name = message.pid.patient_name.family_name    # 'SMITH'
patient_class = message.pv1.patient_class             # 'I'

# .. or positional path expressions ..
given_name = message.get('PID.5.2')                   # 'JOHN'
message_type = message.get('MSH.9.1')                 # 'ADT'

# .. and the whole message as JSON.
as_json = message.to_json(indent=2)

HL7 batch envelopes - FHS and BHS headers wrapping many messages - arrive over the same channels, with the service receiving the full batch to unpack, as described in batch processing. File-based exchange works with the built-in scheduler - a job picks up files on an interval and feeds each message through the same services that handle MLLP traffic, so the processing logic exists once.