Omni-channel alerts

Preview who an alert event would reach

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
POST
/v1/omnichannel-alerts/preview

Shows who a rule would tell about one alert event for one patient, and over which channels. Nothing is sent and nothing is stored.

Scope: the caller's project (from the token).

Behaviour

  • patientId is the FHIR Patient whose people are resolved. event is the Signals event to try, alert.triggered by default. alert is a sample alert: reason, and optionally code, message and value.
  • notifications tries a rule before you save it; without it, the project's own rule applies.
  • Each notify entry lists its recipients, each with email telling whether they have an address on file, and the unknownChannels and unknownRoles Ovok would skip.
  • withheld lists the people the entry names but Ovok would not tell, because their own access does not cover the alert. Each has a reason:
    • no_account: no active membership in the project.
    • no_patient_access: their access policy does not let them read the patient.
    • no_alert_access: it grants neither signals_alerts:read nor the alert's DetectedIssue.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/omnichannel-alerts/preview' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{"patientId":"PATIENT_ID","event":"alert.triggered","alert":{"code":"8867-4","value":132}}'

Who can call it: a project admin. See roles.

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
patientId*string

The FHIR Patient id whose people are resolved.

Length1 <= length <= 64
event?string

The Signals event to try the rule on.

Default"alert.triggered"
Value in"alert.triggered""alert.empty""alert.note""alert.inactive""alert.refired""alert.resolved""alert.acknowledged"
alert?
Default{}
notifications?

The rule to try, instead of the project's own.

Response Body

Each entry the rule answers for a sample event, and the people it would reach. Nothing is sent.

application/json
  1. response
notify*array<>
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/omnichannel-alerts/preview' \  -H 'Content-Type: application/json' \  -d '{  "patientId": "string"}'
Example Response
{  "notify": [    {      "channels": [        "string"      ],      "to": [        "string"      ],      "recipients": [        {          "reference": "string",          "display": "string",          "email": true        }      ],      "withheld": [        {          "reference": "string",          "display": "string",          "email": true,          "reason": "no_account"        }      ],      "unknownChannels": [        "string"      ],      "unknownRoles": [        "string"      ]    }  ]}

Set the project's omni-channel alerts rule PUT

Sets your project's omni-channel alerts rule. With `OMNICHANNEL_ALERTS_ENABLED` on, Ovok runs it on each alert event Signals sends and tells the people it names by email and push. **Scope:** the caller's project (from the token). ## Behaviour - `logic` is JSON Logic answering up to 10 entries for one event: `{ "notify": { "channels": [...], "to": [...] } }`. An empty list or `null` tells nobody of that event. - The rule reads `event` (`alert.triggered`, `alert.empty`, `alert.note`, `alert.inactive`, `alert.refired`, `alert.resolved` or `alert.acknowledged`), `alert.id`, `alert.code`, `alert.reason`, `alert.message`, `alert.value` and `patient.id`. - `channels`: `push`, `email`. - `to`: `practitioner` (general practitioners and practitioners the patient shares their record with), `caregiver` (active care team members), `relatedPerson` (the patient's related persons) and `sharedWith` (the people the patient shares readings with). - A written-out entry naming a channel or recipient Ovok does not know is refused with `UNKNOWN_NOTIFY_LABELS`. A rule that fails on any event type is refused with `INVALID_NOTIFICATIONS`. ## Example ```bash curl -X PUT 'https://api.sandbox.ovok.com/v1/omnichannel-alerts/rules' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{"logic":{"if":[{"==":[{"var":"event"},"alert.triggered"]},{"notify":{"channels":["push","email"],"to":["practitioner","caregiver"]}},[]]}}' ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).

Email organization codes POST

Emails a user the tenant codes of every organization (project) they have an account in. Use it on a sign-in screen for users who forgot their organization code. **Auth:** none. ## Behaviour - The route always answers 202 with no body and does the work in the background, so the answer does not tell you whether the email has an account. - The background job finds every account with this email, then looks up the tenant code of each project. If there are no accounts or no codes, no email is sent. - The email lists each project's name and code. It uses the `PATIENT_ORGANIZATION_CODES` template when the first account found is a Patient, and `OVOK_ORGANIZATION_CODES` otherwise. Language and domain come from the request. - The email address is lowercased. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/organizations/code/email' \ -H 'Content-Type: application/json' \ -d '{ "email": "max.mustermann@example.com" }' ```