Engine configuration

Configure your integration engine for EDFlow: store and forward, a queued destination that never holds the queue on AE or AR, signing and token refresh at send time, surviving a 30-minute outage, heartbeats and rosters, dead letters, and Mirth Connect / OIE templates with Rhapsody and Cloverleaf notes.

These rules keep a hospital's EHR feeds safe no matter what happens to EDFlow. They apply to every engine.

The rules

Store and forward. Your source connector acknowledges the EHR as soon as the message is persisted. EDFlow is a separate, queued destination. The EHR-facing ACK never waits for EDFlow.
Never hold the queue on AE or AR. Data problems come back as AA with warnings and are dead-lettered in EDFlow; AE (structural) and AR (channel configuration) go to your error channel and alert. Mark the message sent. See the ACK table.
Transient failures pause, they don't error. 503 and 429 carry Retry-After: keep the message queued and retry after the delay, with no hot retry loop.
Sign and authenticate at send time. Fetch or refresh the access token, and compute any HMAC signature, in the destination step that sends, never in the transformer. Queued retries hours later then carry a fresh token and signature.
Idempotency. Derive event ids from the feed and MSH-10 (or send a per-message UUID), and send an Idempotency-Key per message, so a resend after a timeout returns the stored result.
One queue per feed, single-threaded, so events for a visit arrive roughly in order.
Minimum necessary. Filter to ED visits (PV1-2 = E and ED locations). Encrypt message storage, remove content on completion, and never log a token, a secret or a message body.

Surviving an outage

The outage_recovery conformance profile makes EDFlow unavailable to your app for 30 minutes. Your engine keeps queueing; after recovery, every queued message must arrive with no 401, no idempotency_conflict and no gap. This works only if rules 3 to 5 hold. Run it in the sandbox before go-live.

Scheduled channels

system.heartbeat every 60 seconds per feed.
department.roster_reported every 15 minutes, from the engine's census table or a census query the site already runs.
At go-live, a census sync as mode: "backfill" events.

Dead letters

Rejected and expired events land in EDFlow's dead-letter queue, not yours. You're told through the ingest.dead_lettered webhook and GET /v1/events?status=dead_lettered. The integration analyst fixes the cause (usually the mapping) and replays from EDFlow; the replay supersedes the earlier result.

Mirth Connect and Open Integration Engine templates

Channel exports for Mirth Connect 4.x and OIE implement every rule above. Import the code templates first and link them to every channel.

File	What it does
Code templates	Configuration-map access, the client-credentials token cache, the dispatch-time send, the `Retry-After` pause, ACK classification and response mapping
Raw HL7 sender	MLLP listener → queued JavaScript Writer → `POST /v1/hl7v2` (raw). Recommended
Normalized events	MLLP listener → transformer building normalized events for ADT A01/A04/A02/A03/A11, ORM O01 and ORU R01 → `POST /v1/events/batch`. For sites that map at the engine
Webhook receiver	HTTP listener that verifies Standard Webhooks signatures (every signature, every configured secret, ±5 min), deduplicates on `webhook-id`, answers quickly and forwards
Error handler	Receives `AE`/`AR` ACKs and rejected events, keeps codes and positions only, raises an engine alert

Configuration map

Key	Example	Notes
`ingest.api.baseUrl`	the base URL shown in the portal	Each environment has its own host
`ingest.api.clientId`	`edf_test_cli_…`	From the portal
`ingest.api.clientSecret`	(secret store)	Revealed once. Live apps with sensitive scopes use `private_key_jwt` or mTLS
`ingest.api.scope`	`hl7v2:write events:write`
`ingest.api.site`	`your-site-sbx`	Optional; otherwise `MSH-4` maps through the profile
`ingest.api.userAgent`	`Mirth-4.5.0 ADT-sender/1.0`	Identifies your engine in the request log
`ingest.webhook.secrets`	`whsec_…,whsec_…`	Current and, during a rotation, previous
`ingest.webhook.downstream`	channel id	Where verified webhook events go

AR with ERR-3 202 means the processing id isn't accepted in this environment: send T in the sandbox and P in live.

Rhapsody, Cloverleaf and InterSystems

The same rules apply:

Rhapsody: an HTTP communication point in a separate output route with its own queue; compute the token and signature in a send-time JavaScript filter, not in the mapping; route AE/AR to an error route.
Cloverleaf: an outbound thread with store-and-forward recovery; do token and signature work in the TPS procedure attached to the send, and handle replies in the reply TPS without blocking the inbound thread.
InterSystems HealthShare/Ensemble: an HTTP business operation with its own queue and a retry interval honouring Retry-After; build headers in the operation's OnMessage, not in a DTL.