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.
| Item | Example |
|---|---|
A host inside their network that stays on, Windows Server or Linux, with outbound HTTPS (443) to api.sandbox.ovok.com | ovok-agent01 |
| Their receiver's MLLP address, their test system first | kis-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.
- Open the Console and go to EHR connections.
- Select New connection.
- Enter a name, the receiver as
mllp://host:port, and the MRN system. - To send something other than vital signs, enter an Observation search.
- Create the connection.
Or call the API with a project admin's token. A criteria of null sends vital signs.
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.
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:
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:
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:
{
"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.
| Check | Expected result |
|---|---|
Profile in MSH-21 | IHE PCD-01 |
Patient in PID-3 | The MRN |
Code in OBX-3 | 8867-4^Heart rate^LN |
| Value and time | The reading, in UTC with +0000 |
| The hospital's answer | AA 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:
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