Alerts

Say what deserves attention, get told when it opens, claim it, and shelve it when you must.

Set a rule on a field and Dialect opens an alert when it holds, tells people, and closes the alert when a reading shows it’s over. At the end the right people hear about what matters.

Set rules

PUT replaces all of an endpoint’s rules and runs at once, with no confirming.

Set alert rules
RuleFor
{"field": "valve", "is": ["open"]}choice, yes_no, level and colour fields
{"field": "pressure", "above": 70}number fields
{"field": "pressure", "below": 20}number fields

text fields can’t have rules. An endpoint can have up to 20.

OptionMeans
for_sHow long it must hold before opening, 0 to 86,400. At least every_s when not 0
clear_for_sHow long it must be over before closing, 0 to 3,600
if_no_sure_value_for_sAlso open if the field has had no sure value this long, 600 to 86,400. At least two reads
prioritylow, high (default) or urgent
remind_every_sRemind while open and unclaimed, 300 to 86,400
ends_below, ends_aboveOn above or below: where it ends, so a reading near the line doesn’t flap

Call GET /v1/endpoints/{name}/alerts to check. You should see each rule with its rule key, such as pressure:above:70 or valve:is:open, and its sentence, such as Pressure is above 70 psi (ends below 68).

Know how alerts behave

  • Only sure readings open or close an alert, except that if_no_sure_value_for_s opens one with no value. A sure reading then closes it like any other.
  • An unsure reading pauses the clock on for_s and clear_for_s, and never resets it. Set if_no_sure_value_for_s to hear about it when that lasts.
  • Silence never closes an alert. A reading does, or pausing or stopping the endpoint, or removing the rule.
  • Alerts are held back while the gateway has been silent for over 2 minutes, with inhibited_by: "gateway_silent".

See alerts

List open alerts

state is pending, open or closed. By default you get pending and open. Closed gives the latest 50. You should see:

Response with one open alert

close_reason is reading, endpoint_paused, endpoint_stopped or rule_removed. A pending alert’s progress says how far along it is, such as Above 70 psi for 40 of 120 s.

Claim an alert

Say someone’s on it. The first claim wins, later calls add a note, and claiming never closes it. Reminders stop while a claim is current.

Claim an alert

The alert’s handling then holds the claim.

  • A note can be up to 500 characters.
  • A claim goes stale after 2 hours with no note while the alert is open, and reminders resume.
  • An urgent alert unclaimed 15 minutes after people were told escalates once: administrators are emailed and an alert.escalated webhook goes out. Only urgent alerts escalate.

Shelve a rule

During planned work, stop a rule telling anyone for up to 24 hours. Its alerts keep opening and closing. One still open when the shelf ends is told as if it had just opened.

Shelve a rule

DELETE on the same path takes it off the shelf.

Get told

  • In the console: open alerts show under Needs you. An endpoint with no rules adds nothing there.
  • By email: off by default for each endpoint. PUT /v1/endpoints/{name}/email-alerts with {"on": true, "recipients": [...]} turns it on, with people’s identity IDs as recipients. GET on the same path lists who can receive them under people. Alerts close together are batched, within 30 seconds and up to 25 to an email.
  • By webhook: alert.opened, alert.closed, alert.handled, alert.shelved and alert.escalated. See Webhooks.

Watch for gateway alerts

Dialect opens these itself. They appear in GET /v1/alerts, and administrators are emailed. They can’t be claimed, shelved or escalated.

kindOpens whenCloses when
gateway_offlineA gateway in use has been silent for 5 minutesIt’s heard again (heard), or says it stopped (stopped)
gateway_healthA problem such as disk_low or hot has held for 10 minutesIt has been clear as long (cleared)

Their endpoint, field and rule are null. A gateway stopped on purpose opens no alert.

Next steps