Signals with Ovok

Use Signals as part of an Ovok app: FHIR Observations go to Signals, and its alerts come back into FHIR as DetectedIssue, Flag and Observation interpretation.

Build on Ovok's FHIR data and let Ovok run Signals for you. You write Patient and Observation resources as usual; Ovok sends the readings to your project's Signals tenant, and writes Signals' alerts back into FHIR. You never call Signals yourself.

Two project settings turn the two directions on and off:

SettingDirectionWhat it doesDefault
SIGNALS_SEND_AUTOFHIR → SignalsEach Observation of a patient created through the FHIR API is sent to Signals, and enrols the patient on the first reading.Off
SIGNALS_ANNOTATE_OBSERVATIONSSignals → FHIREach alert becomes a DetectedIssue, each episode a Flag, and the breaching reading gets an interpretation.Follows SIGNALS_SEND_AUTO

Flows shows what each combination does. Both need your project to have its own Signals tenant. A third setting, SIGNALS_MTLS_ENABLED, requires client certificates on calls you make to Signals yourself.

How a reading flows

  1. Your app creates an Observation for a patient through POST /fhir/R4/Observation (or in a bundle).
  2. Ovok's Medplum notifies Ovok of the new Observation, and Ovok forwards it to Signals. A patient Signals does not know yet is enrolled by this first reading.
  3. Signals judges the reading against the patient's triggers. A breach raises an alert, and, with episodes on, opens or extends an episode.
  4. Signals tells Ovok, and Ovok writes the result into FHIR: a DetectedIssue for the alert, a Flag for the episode, and an interpretation on the reading.
  5. Your app reads them with ordinary FHIR searches, or shows them through the Slim notification feeds.

Not every new Observation is sent. Ovok skips one whose subject is not a Patient, one with status entered-in-error or cancelled, and one carrying an ovok-event-id or Signals identifier. Readings from connected devices that arrive through Data Ingestion carry ovok-event-id: the ingest path forwards them itself, whatever SIGNALS_SEND_AUTO says.

How an episode behaves

An episode is one clinical event for one patient and one vital. It opens on the first breaching reading, takes in the readings that follow, and closes for one of the reasons below. Ovok shows it as a Flag with annotations on, and as a row of the Slim medical and out-of-bed notification feeds.

  • For banded vitals such as heart rate and breathing rate, a missing value, a value at or below 0, or a non-numeric value gets no verdict: it opens, extends or closes no episode.
  • One in-bed reading ends an out-of-bed absence and clears its acknowledgement silence. The next absent reading starts a new absence.
closeReasonMeaning
RECOVEREDA reading came back inside the limit (for out-of-bed, an in-bed reading). That reading is the episode's last value.
TIMEOUTNo reading of this vital arrived within the disconnect window, so the episode closed at the last reading plus that window.
ACKNOWLEDGEDSomeone acknowledged it while it was open. The next breach opens a new episode.
CROSSEDThe value jumped from one side of the limit to the other. This episode closed and a new one opened for the other side.
THRESHOLD_CHANGEDThe limit that opened the episode was changed or removed.
AWAYThe resident left the bed while a heart-rate or breathing-rate episode was open.
STALEAn out-of-bed episode stayed open longer than 48 hours. No new out-of-bed alert follows until the resident is back in bed.
MANUALOvok closed it because the resident was taken off their sensor or discharged.

Before you start

RequirementDetails
Your own Signals tenantBoth settings work only for a project with a Signals tenant of its own. Turning one on otherwise answers 409 SETTING_NOT_AVAILABLE. Ovok opens a tenant for a new project on its first request; a project that already has patients stays on the shared tenant until Ovok migrates it. See Your Signals tenant.
FHIR accessYour app's access policy needs Observation create, and read on DetectedIssue and Flag to see the results. Project admins manage those policies.
Who changes the settingsProject admins, with PUT /v1/project/settings/:key.

Rules and thresholds

What makes a reading alert is set by triggers and bands in Signals. In an Ovok app, change them through the Slim threshold routes, which save to Signals for you. Products that manage rules themselves can also use the standalone API.

Pages in this section

  • Flows: which setting combination to use, enrolling patients, and where to read alerts.
  • Settings: the switches, their defaults, and what saving them does.
  • Alerts in FHIR: the resources Ovok writes, and how to search them.
  • Gotchas: what to know before you rely on it.

Last updated on

On this page