Skip to content
LambogeniusDocs

HL7 Edge Gateway

Admin console

Watch routes and queues, pause and retry, manage dead letters, and install licenses.

Runs onWindows · Linux · macOS · DockerFree developer license for test traffic. Production traffic needs a paid license.

Everything at the admin address

Open http://<admin.listen>/. When listen isn't a loopback address, the console needs a way in: people sign in with single sign-on or a password, and scripts use API tokens. What each person sees and may do depends on their role. See Console users and roles. The page refreshes every few seconds.

The admin console: a trial license, five routes with their sources, destinations, queues, counters and last errors, and one node
Five routes on one node: lab results over MLLP to a REST API, orders from a REST API into MEDITECH over MLLP, a SOAP service, pharmacy retrying while its API returns 503, and radiology orders in dead letters.
  • License: edition, organization and expiry, with Install token.
  • Routes: each route's source and destination, queue depth, dead letters, counters and last error, with pause, resume and Retry now.
  • Queues and dead letters: browse them, move a message to dead letters, requeue or delete it.
  • Filter tester: paste messages and see which destinations of a route would get them, or try a filter of your own, condition by condition. See Check a filter.
  • Transform tester: paste messages and see what a destination's transform would send it, with the HL7 changes marked. See Check a transform.
  • Message contents: hidden unless allow_payload_view = true and the person has the view_payload grant. Each view is in the audit trail, because messages hold PHI. For a destination with a transform, the viewer also shows the message as sent to it.
  • Audit: for auditors and admins, the audit trail filtered by person, action, route and time, with CSV export. See Audit trail.
  • Cluster: every node, its license, what it is delivering and when it was last seen.

Route states

StateMeaning
idleThe queue is empty, or the next message is on its way.
deliveringA message is being sent to the destination now.
retrying ×NThe destination failed (unreachable, timeout, 408, 429, 5xx or AE). The head message waits for its next attempt; N is the attempts so far.
blockedThe destination rejected the head message and the route has on_reject = "block". Fix the destination and select Retry now, or move the message to dead letters.
pausedAn operator paused delivery. Messages are still accepted and queued.
—A pass-through route: nothing is queued, so there is no delivery state.

Queues and dead letters

Select a route to open its queue. The first message is the one in flight; the rest wait behind it in order.

The pharmacy-rde queue: seven RDE^O11 messages, the first in flight after five attempts
A store-and-forward queue while its target is down. Dead-letter moves a message aside so the rest can go; Delete removes it for good.

The Dead letters tab lists the messages the destination rejected or that ran out of attempts, with the reason. Requeue puts one back at the end of the queue once the cause is fixed. With allow_payload_view = true, View shows the message itself.

A dead-lettered ORM^O01 radiology order with its control ID, attempts, reason and HL7 segments
A dead letter in the message viewer: the reason the destination gave, and the message with its segments highlighted. Copy puts it on the clipboard with HL7 line endings.

Monitoring endpoints

PathUse
/healthThe process is up.
/readyThe node can take traffic: its store is reachable. Use it for load balancer health checks.
/metricsPrometheus metrics per route: received, delivered, rejected, queue depth and more.

The Docker image's health check runs hl7-edge-gateway health, which asks the console for /health with the configuration the gateway runs with (HL7EDGE_CONFIG or HL7EDGE_CONFIG_TOML): over HTTPS when admin.tls is set, trusting only that certificate. Use the same command for any monitoring that runs a command.