Connect over HL7 v2

Make an HL7 connection, install the agent inside the hospital network, and send vital signs to the hospital's CIS.

Send the vital signs in your project to a hospital's CIS as HL7 v2 messages.

Complexity
3/5
Clients
Console, HTTP, hospital host
Time
1 hour, plus the hospital's sign-off

Gather what you need from the hospitalConsole

Ask the hospital for these before you start.

ItemExample
A host inside their network that stays on, Windows Server or Linux, with outbound HTTPS (443) to api.sandbox.ovok.comovok-agent01
Their receiver's MLLP address, their test system firstkis-test.hospital.local:2575
The system of their patient identifier (MRN)urn:oid:1.2.276.0.76.4.8
Which readings they want. Vital signs are the default.Vital signs
An interface analyst who signs the feed off

Make the connectionConsole

You must be a project admin.

  1. Open the Console and go to EHR connections.
  2. Select New connection.
  3. Enter a name, the receiver as mllp://host:port, and the MRN system.
  4. To send something other than vital signs, enter an Observation search.
  5. Create the connection.

Or call the API with a project admin's token. A criteria of null sends vital signs.

create-connection.sh
curl --request POST 'https://api.sandbox.ovok.com/v1/hl7-connections' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "St. Example KIS",
    "destination": "mllp://kis-test.hospital.local:2575",
    "patientIdentifierSystem": "urn:oid:1.2.276.0.76.4.8",
    "criteria": null
  }'

The answer returns 201 with a Location header and a credentials object: baseUrl, clientId, clientSecret and agentId.

The secret is shown once and never listed again. Pass it to the hospital's administrator over an encrypted channel, never in a ticket or chat.

Install the agentTerminal

Run this on the hospital's host. The agent is the open-source @medplum/agent package: use the Windows installer, or Node.js on Linux.

Give the agent the four values from the connection:

agent.properties
baseUrl=https://api.sandbox.ovok.com/
clientId=<clientId>
clientSecret=<clientSecret>
agentId=<agentId>

The agent signs in at /oauth2/token and opens wss://api.sandbox.ovok.com/ws/agent. It connects out only: the hospital opens no inbound port.

Verify your integrationConsole

The connection shows the agent as connected within seconds. Or read it:

get-connection.sh
curl 'https://api.sandbox.ovok.com/v1/hl7-connections/<connection id>' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"
{ "agent": { "status": "connected" } }

If it stays disconnected, see Troubleshooting.

Put the MRN on each patientServer-side

The hospital matches a patient by MRN. Every Patient you want to send needs an identifier in the hospital's system:

patient.json
{
  "resourceType": "Patient",
  "identifier": [
    {
      "system": "urn:oid:1.2.276.0.76.4.8",
      "value": "MRN-9",
      "assigner": { "display": "KIS" }
    }
  ]
}

assigner.display is optional. It is sent as the assigning authority. Set the identifier when you register the patient, or update the patient later. A reading for a patient without it is not sent.

Test your integrationServer-side

Create a heart rate Observation for a test patient that has the MRN. Ask the hospital's analyst to confirm what arrives.

CheckExpected result
Profile in MSH-21IHE PCD-01
Patient in PID-3The MRN
Code in OBX-38867-4^Heart rate^LN
Value and timeThe reading, in UTC with +0000
The hospital's answerAA or CA

Write down the analyst's mapping notes: sender names in MSH-3 to MSH-6, the device id in OBX-18, MDC codes and the MSH-11 processing id (P or T).

Go liveConsole

Make a second connection to the hospital's live interface, with the same steps and a new agent. Then remove the test connection.

Remove a connectionConsole

In the Console, delete the connection under EHR connections. Or:

delete-connection.sh
curl --request DELETE 'https://api.sandbox.ovok.com/v1/hl7-connections/<connection id>' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

The agent's credentials stop working at once and nothing more is sent. Ask the hospital to uninstall the agent.

See also

Last updated on

On this page