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 selects Handlers, which transform or filter messages. Address HL7 fields by path. Return an empty list from a Router to leave a message unrouted. Return 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 to check the links between Connections, Routers, and Handlers. Use the same check in continuous integration.

python -m messagefoundry check --config config

5. Test it, then run it

Run the engine and send a sample message. Each message has a recorded outcome: routed, filtered, or unrouted. Routers and Handlers are Python functions, so you can also unit-test them.

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