# Signals with Ovok

Canonical page: https://docs.ovok.com/signals/connected-ovok

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:

| Setting | Direction | What it does | Default |
| --- | --- | --- | --- |
| [`SIGNALS_SEND_AUTO`](/signals/with-ovok/settings#signals_send_auto) | FHIR → Signals | Each Observation of a patient created through the FHIR API is sent to Signals, and enrols the patient on the first reading. | Off |
| [`SIGNALS_ANNOTATE_OBSERVATIONS`](/signals/with-ovok/settings#signals_annotate_observations) | Signals → FHIR | Each alert becomes a `DetectedIssue`, each episode a `Flag`, and the breaching reading gets an `interpretation`. | Follows `SIGNALS_SEND_AUTO` |

[Flows](/signals/with-ovok/flows#what-each-combination-does) shows what each combination does. Both need your project to have its own Signals tenant. A third setting, [`SIGNALS_MTLS_ENABLED`](/signals/with-ovok/settings#signals_mtls_enabled), requires [client certificates](/signals/standalone/mtls) on calls you make to Signals yourself.

## How a reading flows [#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`](/signals/with-ovok/fhir-annotations#the-alert-detectedissue) for the alert, a [`Flag`](/signals/with-ovok/fhir-annotations#the-episode-flag) for the episode, and an [`interpretation`](/signals/with-ovok/fhir-annotations#the-reading-observation) on the reading.
5. Your app reads them with ordinary FHIR searches, or shows them through the Slim [notification feeds](/slim-apis/notifications/list-medical-notifications).

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](/data-ingestion) carry `ovok-event-id`: the ingest path forwards them itself, whatever `SIGNALS_SEND_AUTO` says.

## How an episode behaves [#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.

| `closeReason` | Meaning |
| --- | --- |
| `RECOVERED` | A reading came back inside the limit (for out-of-bed, an in-bed reading). That reading is the episode's last value. |
| `TIMEOUT` | No reading of this vital arrived within the disconnect window, so the episode closed at the last reading plus that window. |
| `ACKNOWLEDGED` | Someone acknowledged it while it was open. The next breach opens a new episode. |
| `CROSSED` | The value jumped from one side of the limit to the other. This episode closed and a new one opened for the other side. |
| `THRESHOLD_CHANGED` | The limit that opened the episode was changed or removed. |
| `AWAY` | The resident left the bed while a heart-rate or breathing-rate episode was open. |
| `STALE` | An out-of-bed episode stayed open longer than 48 hours. No new out-of-bed alert follows until the resident is back in bed. |
| `MANUAL` | Ovok closed it because the resident was taken off their sensor or discharged. |

## Before you start [#before-you-start]

| Requirement | Details |
| --- | --- |
| Your own Signals tenant | Both 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](/signals/standalone#your-signals-tenant). |
| FHIR access | Your 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 settings | Project admins, with `PUT /v1/project/settings/:key`. |

## Rules and thresholds [#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](/slim-apis/threshold/get-patient-effective-threshold-v2), which save to Signals for you. Products that manage rules themselves can also use the [standalone API](/signals/standalone).

## Pages in this section [#pages-in-this-section]

- [Flows](/signals/with-ovok/flows): which setting combination to use, enrolling patients, and where to read alerts.
- [Settings](/signals/with-ovok/settings): the switches, their defaults, and what saving them does.
- [Alerts in FHIR](/signals/with-ovok/fhir-annotations): the resources Ovok writes, and how to search them.
- [Gotchas](/signals/with-ovok/gotchas): what to know before you rely on it.

## Related [#related]

- [Signals standalone](/signals/standalone)
- [Signals route policies](/access-policies/signals)
- [Data Ingestion](/data-ingestion)
