# Connect over HL7 v2

Canonical page: https://docs.ovok.com/guides/connect-your-ehr/connect-over-hl7

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

<Effort complexity={3} clients="Console, HTTP, hospital host" time="1 hour, plus the hospital's sign-off" />

## Gather what you need from the hospital [Console] [#gather-what-you-need-from-the-hospital-console]

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 connection [Console] [#make-the-connection-console]

You must be a project admin.

1. Open the [Console](https://ovok.com/console?ref=docs) 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.

```bash title="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`.

<Callout type="warn">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.</Callout>

## Install the agent [Terminal] [#install-the-agent-terminal]

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:

```properties title="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 integration [Console] [#verify-your-integration-console]

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

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

```json
{ "agent": { "status": "connected" } }
```

If it stays `disconnected`, see [Troubleshooting](/guides/connect-your-ehr/troubleshooting#the-agent-shows-disconnected).

## Put the MRN on each patient [Server-side] [#put-the-mrn-on-each-patient-server-side]

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

```json title="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 integration [Server-side] [#test-your-integration-server-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 live [Console] [#go-live-console]

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 connection [Console] [#remove-a-connection-console]

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

```bash title="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 [#see-also]

- [HL7 message reference](/guides/connect-your-ehr/message-reference)
- [Troubleshooting HL7 connections](/guides/connect-your-ehr/troubleshooting)
- [Applications](/applications)
