# Routing rules

Canonical page: https://docs.ovok.com/signals/with-ovok/routing-rules

A rule is one [JSON Logic](https://jsonlogic.com) 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.

```json
{
  "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 [#set-it]

| Route | What it does |
| --- | --- |
| `GET /v1/omnichannel-alerts/rules` | Answers `{ "notifications": { "logic" } }`, or `{ "notifications": null }` when there is no rule |
| `PUT /v1/omnichannel-alerts/rules` | Saves a rule, `{ "logic": ... }`; refuses a channel or recipient Ovok does not know |
| `DELETE /v1/omnichannel-alerts/rules` | Removes the rule and answers `204`; nobody is told of new events |
| `POST /v1/omnichannel-alerts/preview` | Shows 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.

```bash
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 [#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.

| Field | Values |
| --- | --- |
| `channels` | `push`, `email` |
| `to` | `practitioner`, `caregiver`, `relatedPerson`, `sharedWith` ([who each is](/signals/with-ovok/omni-channel-alerts#recipients)) |

## What the rule reads [#what-the-rule-reads]

| Variable | Meaning |
| --- | --- |
| `event` | `alert.triggered`, `alert.empty`, `alert.note`, `alert.inactive`, `alert.refired`, `alert.resolved` or `alert.acknowledged` |
| `alert.id` | The alert's id |
| `alert.code` | The code that fired, for example `8867-4` for heart rate |
| `alert.reason` | The reason the alert fired |
| `alert.message`, `alert.value` | The alert's message and value |
| `patient.id` | The patient's id |

## Preview a rule [#preview-a-rule]

```bash
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:

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

## Examples [#examples]

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

```json
{
  "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:

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

## Errors [#errors]

| Status | Code | Meaning |
| --- | --- | --- |
| [`422`](/errors/validation-failed) | [`UNKNOWN_NOTIFY_LABELS`](/errors/unknown-notify-labels) | An entry names a channel or recipient Ovok does not know, for example a misspelt recipient. |
| [`422`](/errors/validation-failed) | [`INVALID_NOTIFICATIONS`](/errors/invalid-notifications) | The rule fails on some event type; the message names it. |
| [`409`](/errors/conflict) | | The 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.

## Related [#related]

- [Omni-channel alerts](/signals/with-ovok/omni-channel-alerts)
- [Trigger logic](/signals/standalone/trigger-logic)
