Remote Agent Request/Reply
Remote Agent Request/Reply
Remote Agents communication prior to v26 is asynchronous. A message/payload is transferred to the receiver and stored by the target. Once stored, the transfer is considered complete, and no “response payload” is ever returned back to the sender.
There are cases where asynchronous communications doesn’t fit well with a workflow, and a real-time reply is needed from the remote side. Consider a customer system which wants to submit a request/message/payload to a central (Connexion) system and get an immediate reply – for example, an HTTP request that actually returns a payload from the central Connexion system. You can now leverage the remote agent secure communications pipeline for these types of requests.
The same pattern is available going from central Connexion systems out to remote agents. A Connexion workflow can make a request to a remote agent, which then perform local queries and/or return local state.
It effectively allows remote agents to act as facades for central/cloud-based services.
Uses
A sample use is FHIR queries between a central (head-end or cloud) Connexion and a site that runs a Remote Agent, in either direction.
Site to central: a local system queries the central repository
A local system at a site, such as an EHR, makes a FHIR request to a vendor product on site. The product's Remote Agent exposes a FHIR endpoint (the facade), carries the request up to the head end, and Connexion there answers it from the vendor's central FHIR repository. The local system sees an ordinary FHIR server on its own network.
Of course it’s possible for the EHR to go direct to a publicly accessible FHIR endpoint (or via vpn), but by putting remote agent and Connexion layers in the pathway, workflows can react to data flowing in either direction and perform actions on that data. Similarly, a remote agent can act as a general facade, receiving different types of payloads (HL7v2, ccda, fhir, custom, etc.) and routing them all through a central normalizing pathway.
Central to site: a cloud service queries the site's EHR
A cloud product, or a central caller, needs data that only the site's EHR (or PACS, or another on-site system with a API) holds. It calls the facade on Connexion, and the site's Remote Agent answers from the EHR. This direction is useful mainly because of the network and because of who keeps control:
Nothing opens inward at the site. The Remote Agent connects out to the Gateway, so a cloud service can query an on-site EHR without a VPN or an inbound firewall rule. Without it, a cloud product usually copies site data up ahead of time.
Fetch at the moment of need instead of syncing everything. For example, a care-management or prior-authorization app pulls a patient's current medications, allergies or latest labs when a clinician opens the case; a support or reconciliation tool checks whether a result or order reached the site's EHR; a cloud viewer fetches one document on demand.
The site keeps control. The answering channel runs on the site's Remote Agent. The EHR's credentials stay on site, the site decides what is answered (the sample answers only reads and searches), and a records queue on the answering channel gives the site a log of every request the cloud made and what it got back.
Example
Two channels, one on each side of the Gateway:
Calling channel | Answering channel |
|---|---|
HTTP Listener (reply mode Channel result), then a Remote Integrator Outbound Connector in Request reply mode. | Remote Integrator Inbound Connector, then the device that builds the answer (in the sample, an HTTP Sender with custom code that queries the EHR), then optionally a records queue. |
The outbound connector sends the message as a request, waits up to its Reply timeout for the answer, and continues with the answer as its message.
The answering channel processes the request within the call. The message as it leaves that channel is the answer, along with an HTTP status and content type if the channel sets them.
The HTTP Listener in Channel result mode replies to its caller with that answer. The details of the caller's request (method, path, query) travel with the message, so the answering channel can build its query from them.
Any channel can call, not only an HTTP Listener: a queue followed by the outbound connector sends one request at a time and continues down the channel with each answer.
Request Reply Example FHIR Facade
An HTTP Listener on port 8095 (FHIR target, base path /fhir, request details recorded, Channel result, bearer token required), then the outbound connector in Request reply mode with a 30 second timeout.
Request Reply FHIR Query
The inbound connector, an HTTP Sender, then a regular queue, Request and reply records. The HTTP Sender's custom code reads the requested resource or search from the FHIR server and returns the server's own answer and status. It answers reads and searches only.
On a Remote Agent the same channels are edited in the Gateway management UI:
Details
Give both connectors the same new token (Generate Token on the outbound connector, paste it into the inbound one) and make the route.
On the facade's HTTP Listener, set up authentication for your callers (the sample expects a bearer token from your identity provider).
Point the HTTP Sender at your FHIR server, and fill in its EHR credentials if the server needs a token.
Start both channels.
What the sample shows
Caller authentication. The facade requires a bearer token. A request without a valid token is refused at the facade and never crosses the Gateway. The caller's identity travels with the request, but the token itself does not.
Authenticating to the EHR. The answering side signs in to the EHR as a SMART Backend Services client and reuses one access token for many requests. Its credentials stay on the answering side; the caller never sees them.
Paging. A FHIR server's paging links name the server itself, which the caller cannot reach. The sample rewrites them to point back at the facade, so a caller can page through a large search as if it were talking to the server directly.
Recording each exchange
The query channel keeps a record of every exchange in its Request and reply records queue: the answer the caller got, with the request details, the response status and the time the EHR took. Storing the record is the only part done while the caller waits. Any processing added after the queue (for example, follow-up work based on the request that came in) runs separately and never holds the caller. If a record cannot be stored, a warning is logged and the caller still gets the answer.
Good to know
Queues. The answer is the message as it leaves the answering channel, so a regular queue can't sit in the request's path (a synchronous queue can). A records queue that the answering device posts to, as in the sample, is fine.
Failures. If the remote side is offline, the answering channel is stopped, or no answer comes within the Reply timeout, the caller gets an error (HTTP 500 with a generic message). The details stay in the logs on each side. Nothing retries automatically; the caller retries.
Size and speed. An answer can be up to 15 MiB. In testing, each exchange added roughly 10 ms over calling the FHIR server directly, and concurrent requests do not wait for each other.
Security. Request/reply opens no new ports. It uses the existing mutually authenticated connections between Remote Agent, Gateway and Connexion, and a request only crosses between a paired outbound and inbound connector with a route between them.