Optional: Receive readings over HL7 v2

Take every reading back into your Supabase as an HL7 v2 message through Ovok's HL7 agent, filed under the right patient by the pseudonym.

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 a hospital would.

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

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 connectionServer-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.

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 readingsServer-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:

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 receiverServer-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:

AnswerWhen
AAThe readings are stored.
ARThe message is malformed or the pseudonym is not in the register. A retry cannot help.
AEThe database refused the write. Ovok retries.
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 agentTerminal

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:

agent.properties
baseUrl=https://api.sandbox.ovok.com/
clientId=<clientId>
clientSecret=<clientSecret>
agentId=<agentId>
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

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

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 describes.

See also

Last updated on

On this page