Routing rules

The JSON Logic rule Ovok runs on each Signals alert event to name who is told, and over which channels.

A rule is one JSON Logic expression. Ovok runs it on each alert event Signals sends and tells the people it names. Ovok stores the rule with the project, not in Signals.

{
  "logic": {
    "if": [
      { "==": [{ "var": "event" }, "alert.triggered"] },
      { "notify": { "channels": ["push", "email"], "to": ["practitioner", "caregiver"] } },
      { "==": [{ "var": "event" }, "alert.refired"] },
      { "notify": { "channels": ["push", "email"], "to": ["relatedPerson", "sharedWith"] } },
      []
    ]
  }
}

Set it

RouteWhat it does
GET /v1/omnichannel-alerts/rulesAnswers { "notifications": { "logic" } }, or { "notifications": null } when there is no rule
PUT /v1/omnichannel-alerts/rulesSaves a rule, { "logic": ... }; refuses a channel or recipient Ovok does not know
DELETE /v1/omnichannel-alerts/rulesRemoves the rule and answers 204; nobody is told of new events
POST /v1/omnichannel-alerts/previewShows who a rule would reach for one patient and event; sends nothing

The rules routes are for project admins. The project needs a Signals tenant of its own.

curl -X PUT 'https://api.sandbox.ovok.com/v1/omnichannel-alerts/rules' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"logic":{"if":[{"==":[{"var":"event"},"alert.triggered"]},{"notify":{"channels":["push","email"],"to":["practitioner","caregiver"]}},[]]}}'

What the rule answers

The rule answers zero to 10 entries, each { "notify": { "channels": [...], "to": [...] } }. Answer a single entry, a list of them, or an empty list to tell nobody about that event.

FieldValues
channelspush, email
topractitioner, caregiver, relatedPerson, sharedWith (who each is)

What the rule reads

VariableMeaning
eventalert.triggered, alert.empty, alert.note, alert.inactive, alert.refired, alert.resolved or alert.acknowledged
alert.idThe alert's id
alert.codeThe code that fired, for example 8867-4 for heart rate
alert.reasonThe reason the alert fired
alert.message, alert.valueThe alert's message and value
patient.idThe patient's id

Preview a rule

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

The body takes patientId, an optional event (default alert.triggered), an optional alert with reason, code, message and value, and an optional notifications rule to try instead of the saved one. The answer is:

{
  "notify": [
    {
      "channels": ["push", "email"],
      "to": ["practitioner"],
      "recipients": [{ "reference": "Practitioner/123", "display": "Dr Example", "email": "dr@example.com" }],
      "unknownChannels": [],
      "unknownRoles": []
    }
  ]
}

Examples

Tell the care team of a new alert, and family when it fires again:

{
  "logic": {
    "if": [
      { "==": [{ "var": "event" }, "alert.triggered"] },
      { "notify": { "channels": ["push"], "to": ["caregiver"] } },
      { "==": [{ "var": "event" }, "alert.refired"] },
      { "notify": { "channels": ["push", "email"], "to": ["relatedPerson"] } },
      []
    ]
  }
}

Tell nobody about inactivity events, and email the practitioner for the rest:

{
  "logic": {
    "if": [
      { "==": [{ "var": "event" }, "alert.inactive"] },
      [],
      { "notify": { "channels": ["email"], "to": ["practitioner"] } }
    ]
  }
}

Errors

StatusCodeMeaning
422UNKNOWN_NOTIFY_LABELSAn entry names a channel or recipient Ovok does not know, for example a misspelt recipient.
422INVALID_NOTIFICATIONSThe rule fails on some event type; the message names it.
409The project changed while the rule was written. Repeat the request.

A rule that fails while it runs tells nobody of that event and is logged. Try a rule with POST /v1/omnichannel-alerts/preview before you save it.

Last updated on

On this page