Alarms

An alarm tells people that a condition needs attention. Alarm rules raise and clear alarms on their own; automations raise and clear them with raiseAlarm and clearAlarm steps. Every member sees them on the workspace’s Alarms page; operators, editors, admins and owners acknowledge and shelve them there, from a dashboard’s alarm list, or through the API.

Lifecycle

An alarm is active from the moment it is raised until it is cleared. A raised alarm may be acknowledged at any time, with an optional comment; the acknowledgement records who and when.

• A non-latching alarm leaves the active alarms as soon as it is cleared, acknowledged or not.
• A latching alarm that clears before anyone acknowledges it stays, cleared, until someone does. Raised again meanwhile, it becomes active again as the same alarm, still waiting for its acknowledgement.
• An alarm acknowledged while active stays until it clears.

Each alarm belongs to the rule or automation that raised it, under a key: an automation’s own key, or alarm for a rule’s alarm and unavailable for the rule’s input-unavailable alarm. Keys are unique per rule or automation: an automation never changes an alarm another one, or a rule, raised under the same key text.

When a rule or automation is disabled or deleted, or its dashboard is disabled, its alarms are removed. So are an automation’s alarms of keys it no longer raises after an edit, and a rule’s unavailable alarm once the rule no longer has unavailableAfterMs. The alarm log records each removal.

Alarm rules

A rule is checked when an input it reads changes, also when it becomes unknown; when one of its hold times is up; and every pollIntervalMs when its condition reads the time. It is checked at most once per pollIntervalMs: changes in between are checked together at the end of the interval, and a condition that breaks a hold meanwhile still starts it over. Each check counts as one automation step, under the rule.

• The alarm is raised once condition has been true for holdMs, and cleared once clearCondition (by default not condition) has been true for clearHoldMs (by default 0).
• An unknown condition never raises or clears the alarm. It starts the hold over, so an input that comes and goes cannot raise or clear an alarm early.
• With unavailableAfterMs, the unavailable alarm is raised when the condition that decides next (the clear condition while the alarm is active, otherwise the condition) has been unknown that long. It clears once that condition is known again. Its notification says the rule’s inputs are unavailable; it is never latching.
• The message’s parameters are taken when the alarm is raised.
• Hold times survive server restarts. Editing, disabling or enabling a rule starts its holds over; an alarm it already raised stays until the rule clears it or is disabled.

Automations

• raiseAlarm raises the automation’s alarm under key. While that alarm is active, it takes the new severity, message, latching, recipients and delay without logging or notifying again.
• clearAlarm clears it.
• An alarm input is true while the alarm is active (raised and not cleared), false otherwise, also after it left the active alarms. With "state": "unacknowledged" it is true while the alarm is raised and nobody acknowledged it, also while a latching alarm waits after clearing. It is never unknown. Reading the state rather than reacting to alarm triggers keeps an automation right when transitions come faster than its runs: runs of different procedures are spaced apart separately, so their order can differ from the transitions’.
• An alarm trigger starts a run when the alarm is raised, acknowledged or cleared. A latching alarm acknowledged after it cleared is acknowledged once.
• Raising and clearing happen when the run is stored; a failed run raises or clears nothing.

An automation that reads an alarm’s state through alarm inputs, with an inputChange trigger on them and a held if branch, can escalate an alarm that nobody acknowledged in time; see Escalate an unacknowledged alarm.

Notifications

An alarm notifies its recipients when it is raised, after notifyDelayMs rounded up to whole seconds, with its severity and message. Without recipients it notifies nobody. When a member chosen by id leaves the workspace, the alarm rule has an error and is no longer evaluated until they are removed from its recipients.

• A notification still waiting for its delay is dropped when the alarm clears, is acknowledged or is shelved first. One already sent is withdrawn from the notification banners.
• Acknowledging, clearing and shelving notify nobody.
• A shelved alarm does not notify. When its shelf ends and it is still active and unacknowledged, its recipients are notified at once.

Alarm notifications arrive in the notification center and on the channels each recipient chose, like other notifications.

Alarm notifications, including the one sent when a shelf ends, link to the workspace’s Alarms page: email shows an action button and Telegram an Open in Overvis HMI button. The message needs no URL of its own.

Alarms page

Alarms (/workspace/<id>/alarms) is at the foot of the workspace sidebar of every member, above Setup… for editors, admins and owners and in its place for operators and viewers. It shows once the workspace raises alarms: it has an enabled alarm rule, an enabled automation with a raiseAlarm step, or an active alarm. Its badge counts the alarms waiting for someone: not acknowledged and not shelved, cleared latching ones included. On a phone, a dot on the menu button says alarms are waiting. The page itself, and the links in alarm notifications, work in every workspace.

• Active lists the active alarms live, those waiting for acknowledgement first, then by severity and newest first. Each shows its severity, message, when it was raised and cleared, the rule or automation that raised it, and who acknowledged or shelved it, with the comment or reason.
• An alarm rule’s alarm for inputs that stay unknown reads Alarm inputs unavailable: and the rule’s name, and says to check the devices.
• History is the alarm log, newest first, filtered by severity, event, source, period or one alarm. History on an active alarm opens its own events. The filters are part of the page address, so a filtered view can be shared as a link.

Operators, editors, admins and owners act on alarms; view-only members see them.

• Acknowledge takes an optional comment of up to 500 characters. An alarm can be acknowledged once.
• Shelve shelves it for 15 minutes, 1, 8 or 24 hours, or 7 days, with a reason of up to 500 characters. A shelved alarm stays in the list. Shelving a shelved alarm replaces its shelf. A shelf ends when its time is up, or earlier with End shelf.

A dashboard can show the same live list, filtered to its own alarms, with AlarmList from @overvis/hmi-workspace-ui; integrations use the alarm.* procedures of the API.

The assistant can list alarms and read the alarm log, but cannot acknowledge or shelve them.

Alarm sound

An open workspace tab can play a sound for alarms, but only in a browser where someone turned Alarm sound in this browser on, on the Alarms page. It is off until then, and the setting is kept per browser.

• It sounds for warning and urgent alarms waiting for someone, repeating until they are acknowledged or shelved, and faster for urgent ones. Info alarms never sound.
• Only one tab of the browser plays it per workspace, however many are open.
• While it plays, a bar above the page names how many alarms wait, with View alarms and Silence. Silence stops the sound for the alarms waiting now in every tab of the browser; a new alarm sounds again.
• Browsers keep a page silent until you interact with it. A tab the browser keeps silent never takes the sound from one that can play it. When no tab can, the bar says the browser blocked the sound; the first click or key press on the page, or Allow sound, lets it play.

Alarm log

The alarm log keeps one event per change: raised, acknowledged, cleared, shelved, unshelved and removed, with the alarm’s severity and message, who acknowledged or shelved it, the comment or reason, and when. An event appears within seconds of the change. The Alarms page shows it under History.

The log is stored data of the workspace: it is kept until the retention set on the Stored data page removes it (at least 30 days, or everything is kept), and it counts as alarm log storage in charges. Deleting the workspace deletes its log. When an account is deleted, its acknowledgements and shelves stay in the log without the account.

API

Procedure	What it does	Who
alarm.list	Active alarms, and cleared latching ones waiting for acknowledgement	Members
alarm.watch	Subscription: { alarms, configured } at once and again after each change	Members
alarm.log	The alarm log, newest first, by page (cursor, limit up to 100), filtered	Members
alarm.acknowledge	Acknowledges an alarm by id, with an optional comment	Operators and above
alarm.shelve	Shelves an alarm by id for durationMs (60 000 to 604 800 000) with a reason	Operators and above
alarm.unshelve	Ends an alarm’s shelf	Operators and above

An alarm is { id, workspaceId, source, key, severity, message, latching, raisedAt, clearedAt, acknowledgedAt, acknowledgedBy, acknowledgedByName, acknowledgeComment, shelvedUntil, shelvedBy, shelvedByName, shelveReason, parameterIds }. source is { "kind": "alarm_rule", "alarmRuleId" } or { "kind": "automation", "automationId" }. message is the title and body as written, in every language, with the values of its parameters when it was raised. id names one occurrence, from raising until it leaves the active alarms. acknowledgedByName and shelvedByName are the members’ names now. parameterIds are the parameters the inputs of the raising rule or automation read as it is now, empty once it is gone. A shelvedUntil in the past means the shelf is over and is about to be ended.

alarm.watch sends the whole alarm.list as alarms, and configured, true while the workspace raises alarms (see Alarms page).

alarm.log filters by from and to (ISO times), severities, kinds, sourceIds and alarmId. Each event is { id, alarmId, source, key, kind, severity, message, latching, actorUserId, actorName, note, shelvedUntil, occurredAt }; note is the comment, the reason, or why the alarm was removed. Pass nextCursor back as cursor for the next page.

Errors: alarm_not_found (the alarm is no longer active and waits for no acknowledgement), alarm_already_acknowledged, alarm_not_shelved and alarm_log_invalid_cursor.