# Optional: Receive readings over HL7 v2

Canonical page: https://docs.ovok.com/guides/staffed-kiosk/receive-readings-over-hl7

Your Supabase becomes the clinical information system: each reading saved at the kiosk comes back as an HL7 v2 message and lands in a `readings` table next to the patient. It uses the same [HL7 connection](/guides/connect-your-ehr/connect-over-hl7) a hospital would.

```text
Ovok ──wss──▶ HL7 agent ──MLLP──▶ receiver ──▶ Supabase readings
```

## Before you begin [#before-you-begin]

- The kiosk working end to end from step 4.
- A project admin's Ovok token, to make the connection.
- Node.js on the host that runs the agent and the receiver.

## Make the connection [Server-side] [#make-the-connection-server-side]

Use the register's identifier system as the connection's patient identifier system. `PID-3` of every message then carries the pseudonym, so the receiver needs no MRN. Send only the blood-pressure panel and the heart rate: each kiosk reading also stores the two pressures on their own, and the panel already carries them.

~~~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": "Kiosk CIS",
    "destination": "mllp://127.0.0.1:2575",
    "patientIdentifierSystem": "https://kiosk.example.org/patient-id",
    "criteria": "Observation?code=http://loinc.org|85354-9,http://loinc.org|8867-4"
  }'
~~~

The answer is `201` with the agent's `baseUrl`, `clientId`, `clientSecret` and `agentId`, shown once. The destination is where the agent reaches the receiver, so `127.0.0.1` works when both run on one host.

## Store the readings [Server-side] [#store-the-readings-server-side]

The example's second migration adds the table. A resend from Ovok carries the same control id, so the key makes a retry harmless:

~~~sql title="supabase/migrations/20261113090000_readings.sql"
create table public.readings (
  control_id text not null,
  set_id integer not null,
  patient_id uuid not null references public.patients (id),
  code text not null,
  code_system text,
  display text,
  value numeric not null,
  unit text,
  observed_at timestamptz not null,
  received_at timestamptz not null default now(),
  primary key (control_id, set_id)
);
~~~

Row level security is on with no grants to `anon` or `authenticated`, as for the register.

## Run the receiver [Server-side] [#run-the-receiver-server-side]

`receiver/` is an MLLP server built on Medplum's `@medplum/hl7`. It reads the control id from `MSH-10`, the pseudonym from `PID-3`, and one reading from each numeric `OBX`, then answers:

| Answer | When |
| --- | --- |
| `AA` | The readings are stored. |
| `AR` | The message is malformed or the pseudonym is not in the register. A retry cannot help. |
| `AE` | The database refused the write. Ovok retries. |

~~~bash
cp .env.receiver.example .env.receiver.local
npm run receiver
~~~

Set `SUPABASE_SERVICE_ROLE_KEY` in `.env.receiver.local` from `npm run supabase -- status`. The receiver is the only other component that holds this key; keep it on the same host as the agent.

## Run the agent [Terminal] [#run-the-agent-terminal]

The agent is Medplum's open-source `@medplum/agent`. It connects out to Ovok, so you open no inbound port. Give it the four values from the connection:

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

~~~bash
npm install @medplum/agent@5.0.13
node node_modules/@medplum/agent/dist/cjs/index.cjs
~~~

It logs `Successfully connected` once it has opened `wss://api.sandbox.ovok.com/ws/agent`. On Windows, use Medplum's agent installer.

## Verify your integration [#verify-your-integration]

Save a reading at the kiosk, then read the table:

~~~sql
select r.code, r.value, r.unit, r.observed_at
from public.readings r
join public.patients p on p.id = r.patient_id
where p.card_code = 'WARD-0042';
~~~

You should see three rows within seconds: systolic (`8480-6`), diastolic (`8462-4`) and the pulse. If you don't:

1. The agent log shows each message as a `Request` and your `AA` as a `Response`. No request means the connection's criteria or the patient identifier system don't match.
2. An `AR` in the agent log with "unknown patient" in the receiver log means `PID-3` is not a register id: check `patientIdentifierSystem`.
3. Nothing in the agent log at all: check that it is connected, as [Troubleshooting HL7 connections](/guides/connect-your-ehr/troubleshooting) describes.

## See also [#see-also]

- [Connect over HL7 v2](/guides/connect-your-ehr/connect-over-hl7)
- [HL7 message reference](/guides/connect-your-ehr/message-reference)
- [Run it on the ward](/guides/staffed-kiosk/run-it-on-the-ward)
