Push to Agent | Medplum

We value your privacy

We use cookies to enhance your browsing experience, serve personalised ads or content, and analyse our traffic. By clicking "Accept All", you consent to our use of cookies.

CustomiseReject AllAccept All

Powered by Visit CookieYes website

Customise Consent Preferences

We use cookies to help you navigate efficiently and perform certain functions. You will find detailed information about all cookies under each consent category below.

The cookies that are categorised as "Necessary" are stored on your browser as they are essential for enabling the basic functionalities of the site. ... Show more

NecessaryAlways Active

Necessary cookies are required to enable the basic features of this site, such as providing secure log-in or adjusting your consent preferences. These cookies do not store any personally identifiable data.

No cookies to display.

Functional

Functional cookies help perform certain functionalities like sharing the content of the website on social media platforms, collecting feedback, and other third-party features.

_octo

1 year

No description available.

logged_in

1 year

No description available.

VISITOR_PRIVACY_METADATA

6 months

YouTube sets this cookie to store the user's cookie consent state for the current domain.

__Secure-YNID

6 months

YouTube cookie used to protect user security and prevent fraud, especially during the login process.

__Secure-ROLLOUT_TOKEN

6 months

YouTube sets this cookie to manage feature rollout and experimentation. It helps Google control which new features or interface changes are shown to users as part of testing and staged rollouts, ensuring consistent experience for a given user during an experiment.

__Secure-YEC

past

Description is currently not available.

_gh_sess

session

GitHub sets this cookie for temporary application and framework state between pages like what step the user is on in a multiple step form.

YSC

session

YSC cookie is set by Youtube and is used to track the views of embedded videos on Youtube pages.

VISITOR_INFO1_LIVE

6 months

A cookie set by YouTube to measure bandwidth that determines whether the user gets the new or old player interface.

ytidb::LAST_RESULT_ENTRY_KEY

Never Expires

The cookie ytidb::LAST_RESULT_ENTRY_KEY is used by YouTube to store the last search result entry that was clicked by the user. This information is used to improve the user experience by providing more relevant search results in the future.

Analytics

Analytical cookies are used to understand how visitors interact with the website. These cookies help provide information on metrics such as the number of visitors, bounce rate, traffic source, etc.

_ga

1 year 1 month 4 days

Google Analytics sets this cookie to calculate visitor, session and campaign data and track site usage for the site's analytics report. The cookie stores information anonymously and assigns a randomly generated number to recognise unique visitors.

_ga_*

1 year 1 month 4 days

Google Analytics sets this cookie to store and count page views.

Performance

Performance cookies are used to understand and analyse the key performance indexes of the website which helps in delivering a better user experience for the visitors.

No cookies to display.

Advertisement

Advertisement cookies are used to provide visitors with customised advertisements based on the pages you visited previously and to analyse the effectiveness of the ad campaigns.

No cookies to display.

Uncategorised

Other uncategorised cookies are those that are being analysed and have not been classified into a category as yet.

No cookies to display.

Reject AllSave My PreferencesAccept All

Powered by Visit CookieYes website

Skip to main content

On this page

Introduction [​](/content/docs/agent/push#introduction "Direct link to Introduction"/index.html)

While the Medplum Agent traditionally connected healthcare facilities to cloud services by listening to legacy healthcare protocols and forwarding messages securely to the cloud, it also supports pushing messages from the cloud to on-prem devices.

Feature Overview [​](/content/docs/agent/push#feature-overview "Direct link to Feature Overview"/index.html)

  1. Message Push: Leverage websockets for a persistent connection between the cloud server and on-prem Medplum Agent.
  2. Cloud-Initiated Messages: With the existing connection, the server can initiate messages to be sent directly to remote devices via the agent.
  3. Use Cases:
    • Push order details directly to lab instruments using HL7 or ASTM.
    • Send patient details to radiology modalities using DICOM.
    • Relay a DICOM SR to a RIS using DICOM.
  4. Simplified Infrastructure: Eliminate the need for site-to-site VPNs, making setups more straightforward and secure.

How it works [​](/content/docs/agent/push#how-it-works "Direct link to How it works"/index.html)

First, consider the most simple case: an HL7 device on the network (e.g. a Radiology Information System or Lab Instrument):

We can emulate this setup using the Medplum CLI:

medplum hl7 listen 56000

Next, let's add a simple HL7 client also on the network:

We can emulate this step using the Medplum CLI:

medplum hl7 send localhost 56000 --generate-example

This will send a message and print the reply to the terminal.

The main challenge with HL7 interfaces is the need to be on the local network. Historically, this meant running the EHR software on-premise.

Instead, we will use the Medplum Agent to proxy traffic to the Medplum server hosted in the cloud:

The Medplum Agent connects to the on-premise device the same as any other HL7 client: using HL7 over MLLP.

The power of the Medplum Agent is when connected to a Medplum server:

The Agent connects to the Server using secure WebSockets (WSS). Because WebSockets are a persistent connection, the server can "push" a message to the instrument via the agent.

We can emulate this step using the Medplum CLI. This time, instead of using HL7 over MLLP, we will send a JSON message over HTTPS. The Server forwards the message to the Agent. The Agent forwards the message to the instrument.

medplum post 'Agent/1080ee82-e4fc-4312-946f-322fbecf9bb9/$push' $'{"destination":"Device/52c9a9de-1081-4fb2-a40a-e62efe1b73b2","contentType":"x-application/hl7-v2+er7","body":"MSH|^~\\\\&|ADTSYS|HOSPITAL|RECEIVER|DEST|20231023235305.516||ADT^A01|1698105185516|P|2.5|\\nEVN|A01|20231023235305.516||\\nPID|1|12345|12345^^^HOSP^MR|123456|DOE^JOHN^MIDDLE^SUFFIX|19800101|M|||123 STREET^APT 4B^CITY^ST^12345-6789||555-555-5555||S|\\nPV1|1|I|2000^2012^01||||12345^DOCTOR^DOC||||||||||1234567^DOCTOR^DOC||AMB|||||||||||||||||||||||||202309280900|"}'

This line is intentionally long due to the complexities of escaping new lines. Let's break it down piece by piece:

medplum post 'Agent/1080ee82-e4fc-4312-946f-322fbecf9bb9/$push' $'{

"destination": "Device/52c9a9de-1081-4fb2-a40a-e62efe1b73b2",

"contentType": "x-application/hl7-v2+er7",

"body": "MSH|^~\\\\&|ADTSYS|HOSPITAL|RECEIVER|DEST|20231023235305.516||ADT^A01|1698105185516|P|2.5|\\n\

EVN|A01|20231023235305.516||\\n\

PID|1|12345|12345^^^HOSP^MR|123456|DOE^JOHN^MIDDLE^SUFFIX|19800101|M|||123 STREET^APT 4B^CITY^ST^12345-6789||555-555-5555||S|\\n\

PV1|1|I|2000^2012^01||||12345^DOCTOR^DOC||||||||||1234567^DOCTOR^DOC||AMB|||||||||||||||||||||||||202309280900|"\

}'

How To Use The Feature [​](/content/docs/agent/push#how-to-use-the-feature "Direct link to How To Use The Feature"/index.html)

  1. Direct Push:
    • Send an HTTPS POST request to /Agent/{id}/$push.
    • The content body should be a JSON object with the following properties:
      • destination - Device reference (i.e., Device/123) or a Device search (i.e., Device?identifier=123)
        • The Device resource must have a Device.url property
      • contentType - MIME type of the content, x-application/hl7-v2+er7 for HL7 v2
      • body - the actual HL7 message body
    • The Medplum server will forward the message through websockets, and the Medplum Agent will relay it to the intended device.
  2. Using MedplumClient:
    • MedplumClient, Medplum's JavaScript/TypeScript SDK, simplifies tasks related to connectivity and authentication.
    • To send a message, just use: medplum.pushToAgent(agent, device, body, contentType). The SDK manages the HTTPS POST request for you.
  3. Pushing with Medplum Bots:
    • Medplum Bots allow users to run custom JavaScript or TypeScript logic based on various triggers.
    • Each Bot invocation has a built-in MedplumClient.
    • To push a message, use: medplum.pushToAgent(agent, device, body, contentType).

End-To-End Example: Pushing Lab Orders [​](/content/docs/agent/push#end-to-end-example-pushing-lab-orders "Direct link to End-To-End Example: Pushing Lab Orders"/index.html)

Objective: Push lab orders to a remote device using HL7.

Trigger: "Create" or "Update" operations on a FHIR ServiceRequest.

Steps:

  1. Set up a Medplum Bot.
    • The Bot will receive the FHIR ServiceRequest.
    • It will then convert the required FHIR fields to HL7 using the Medplum HL7 SDK.
  2. Save and deploy your Bot.
  3. Create a FHIR Subscription:
    • Set the criteria to "ServiceRequest".
    • Choose the Bot as the channel target.
  4. Now, any "create" or "update" operation on a FHIR ServiceRequest will trigger the Medplum server to call the Bot. The Bot will process and convert the message to HL7, sending it to the remote device via the Medplum Agent.