Build an HL7 interface in Python

The four building blocks

• Connection — an endpoint that receives (inbound) or sends (outbound) messages over a transport like MLLP, files, HTTP, or a database.
• Router — a function that looks at a message and returns the names of the Handlers that should process it.
• Handler — a function that transforms a message and sends it to an outbound Connection (or filters it).
• Message — the parsed HL7, addressed by path: msg["MSH-9.1"], msg["PID-3"], and so on.

1. Install and create a config directory

Install the engine from PyPI; your interfaces live as Python modules in a config directory you own.

pip install messagefoundry
mkdir config

2. Declare your Connections

Name an inbound Connection to receive messages and an outbound Connection to send them. Point the inbound at a Router.

from messagefoundry import MLLP, Send, inbound, outbound, router, handler

inbound("IB_ADT", MLLP(port=2575), router="adt_router")
outbound("OB_EHR", MLLP(host="10.0.0.21", port=6661))

3. Write a Router and a Handler

The Router decides routing; the Handler does the work. Address HL7 fields by path; return an empty list to leave a message unrouted, or None from a Handler to filter it.

@router("adt_router")
def route(msg):
    if msg["MSH-9.1"] != "ADT":
        return []                    # UNROUTED — not an admit/discharge/transfer
    return ["to_ehr"]

@handler("to_ehr")
def to_ehr(msg):
    return Send("OB_EHR", msg)

4. Validate the interface

Run the commit gate. It checks that every Connection, Router, and Handler is wired correctly before anything ships — the same gate you'd put in CI.

python -m messagefoundry check --config config

5. Test it, then run it

Run the engine and send a sample message. Every message reaches a recorded disposition — routed, filtered, or unrouted — so nothing is ever silently dropped. Because routers and handlers are plain Python, you can also unit-test them like any function.

python -m messagefoundry serve --config config --db messagefoundry.db
# in another shell — send a sample ADT to the MLLP port
python samples/send_mllp.py samples/messages/adt_a01.hl7