HTTP, SOAP and MLLP out

Receive HL7 over HTTPS (REST)

An http source accepts POST requests on its path with the HL7 message as the body. Line feeds are accepted in place of carriage returns. The response is the HL7 ACK, with a status that matches it:

With ack_format = "json" the body is { ack_code, control_id, text, ack } instead. Callers can be required to authenticate: see Security.

# A REST API that sends orders into MEDITECH over MLLPS
[[route]]
name = "orders-to-meditech"
mode = "store_and_forward"

[route.source]
type = "http"
listen = "0.0.0.0:8443"
path = "/hl7/orders"
tls = { cert = "certs/gateway.pem", key = "certs/gateway.key" }   # HTTPS
ack_format = "json"          # or "hl7" (the default): the ACK itself

[route.destination]
type = "mllp"
address = "meditech.hospital.local:6661"
tls = { ca = "certs/meditech-ca.pem" }      # MLLPS; leave it out for plain MLLP on a trusted network

[route.store_and_forward]
on_reject = "block"

curl https://gateway.hospital.org:8443/hl7/orders \
  -H "X-API-Key: <the caller's key>" --data-binary @order.hl7

HTTP/1.1 200 OK
{"ack_code":"AA","control_id":"ORD7001","text":"","ack":"MSH|^~\\&|…\rMSA|AA|ORD7001\r"}

SOAP, in and out

With format = "soap", an http source reads the HL7 message from the request envelope (SOAP 1.1 or 1.2) and answers with the ACK in <Operation>Response, or in your own response_template. By default the message is the text of the first element whose text starts with MSH, so most services need no settings; message_element names it explicitly. A request without HL7 gets a Client fault.

An http destination with format = "soap" sends each message in an envelope. Give it a template with {{message}} where the HL7 goes (escaped, or in CDATA with cdata = true), and the action to call. The service's answer is classified like any other: an HL7 ACK in the response decides, a Client (Sender) fault is a rejection, and a Server (Receiver) fault or an HTTP error is retried.

# A SOAP endpoint in front of a SOAP web service
[[route]]
name = "soap-results"
mode = "passthrough"

[route.source]
type = "http"
listen = "0.0.0.0:8443"       # HTTP routes can share a port, with different paths
path = "/Hl7Service.svc"
format = "soap"
tls = { cert = "certs/gateway.pem", key = "certs/gateway.key" }
soap = { version = "1.1" }    # or "1.2"

[route.destination]
type = "http"
url = "https://results.example.org/Hl7Receiver.svc"
format = "soap"
soap = { version = "1.1", action = "urn:results/Submit", template = "soap/submit.xml" }

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <Submit xmlns="urn:results">
      <Hl7Message>{{message}}</Hl7Message>
    </Submit>
  </s:Body>
</s:Envelope>

Send into MEDITECH over MLLP

An mllp destination keeps one connection open to the receiver and sends one message at a time, waiting up to request_timeout for its ACK. AA (or CA) is delivered, AR is a rejection, and AE, a timeout or a broken connection is retried. If the receiver closed an idle connection, the gateway reconnects and sends again once. With pass-through, the receiver's own ACK goes back to the sender. Add tls for MLLPS, with server_name if the certificate's name differs from the host in address.