Alarms

Overview

ControlBird Alarms is a reactive monitoring system that notifies operators when a condition requires attention. Rather than polling, alarms react to changes as they happen: a behavior watches a field on an entity, and when its value meets a configured condition the alarm transitions into an active state, picks a severity, and surfaces in the operator UI with the appropriate color, symbol, and audible alert. Two apps drive the feature. The Active Alarms app is where operators view, acknowledge, shelve, and annotate triggered alerts, and the Alarms Config app is where administrators define severity levels and behaviors that apply across the system.

Reach for alarms whenever a measured or reported value needs human awareness: a tank level over a limit, a session login event, a device going offline, or a process value drifting out of band. Alarms add state tracking (acknowledgment, shelving, latching), severity-based prioritization, and noise control (delays, deadband, hysteresis) on top of raw field changes, so operators see a curated, prioritized list instead of a firehose of updates.

Key Concepts

• Alarm: a monitored condition. It references a behavior, carries runtime state (acknowledged, shelved, severity), and is the entity that appears as a row in the Active Alarms table.
• Behavior: defines when an alarm fires: which field to watch, how to map the value to a severity, the display message, and any delay or hysteresis.
• Severity: defines how an active alarm looks and sounds: priority, colors, symbol, flash rate, and sound file.
• Group: an optional container that organizes related alarms and tracks aggregate active state.
• State machine: every alarm progresses through a fixed set of states; delay timers introduce intermediate "pending" states to suppress transient noise.
• Acknowledgment vs. clearing: acknowledging records that an operator has seen the alarm; it does not resolve the underlying condition. An alarm clears only when its condition resolves (or, if latching, after a manual reset).

Alarm State Machine

Alarms progress through six states. Delay timers move the alarm into a pending state before committing the transition, which is how transient spikes are filtered out.

Configuration Examples

A temperature behavior

This behavior watches a Temperature field, escalates to Critical above 80, and waits 5 seconds before activating so a momentary spike does not raise the alarm.

AlarmBehavior "High Temperature Alert"
  NotifyField:     Temperature
  SeverityMapping: value > 80 ? "Critical" : "Info"
  DelayOnMs:       5000
  DisplayFormat:   Temperature is {value}°C

Multi-tier severity mapping

Severity expressions can chain conditions to pick from several tiers based on a status field:

Status == 'Critical' ? 'Critical'
  : Status == 'Warning' ? 'High'
  : 'Info'

A Critical severity

A severity defines the row appearance and annunciation. The built-in Critical severity uses a purple-tinted background with a 3-second breathing flash:

AlarmSeverity "Critical"
  Priority:           4
  FlashRate:          3000
  RowBackgroundColor: rgba(142, 68, 173, 0.15)
  RowBorderColor:     #8e44ad

Wiring an alarm together

An alarm links to its behavior and (at runtime) a severity. In the configuration tree these live under the Alarms branch:

Alarm     Alarms/SessionMonitor/LoginActivity
Behavior  Alarms/Behaviors/Session Activity
Severity  Alarms/Severities/Critical

Common Patterns

Operating the Active Alarms app

• Acknowledge a single alarm with the eye icon in its Ack column, or use the header eye icon to acknowledge all. Acknowledging stops the breathing animation but leaves the alarm in place.
• Shelve an alarm (right-click → Shelve) to temporarily hide it for a chosen duration between 15 minutes and 24 hours; notifications are suppressed for that window.
• Add Notes (right-click → Add Notes) to record investigation or resolution details on the alarm.
• Investigate with the context menu's See Alarm History (past occurrences) and See Entity (open the related entity in the Database Browser).
• Filter by severity, time range, message text, and responsibilities. Active filters show as removable chips; Clear All resets them. Pagination supports page sizes of 25, 50, or 100.

Noise control

• Use DelayOnMs / DelayOffMs to ride through transient excursions: the alarm sits in PendingActive / PendingClear during the delay.
• Use Deadband for numeric comparisons so a value hovering at the threshold does not chatter on and off; use HysteresisExpression for custom (non-numeric) logic.
• Set TriggerOnChange: true for configuration-style monitoring to reduce notification volume; use false when every update matters.

Display rules

The behavior's DisplayRule controls how long an alarm stays visible in the table:

• NeverDisplay (0): the alarm tracks state but never appears in the table.
• DisplayUntilCleared (1): stays visible until the underlying condition resolves.
• HideAfterAck (2): removed once acknowledged, regardless of the condition.

Troubleshooting & Limitations

• Alarm never fires. An alarm only triggers when Enabled is true and its attached Behavior is valid. A missing behavior or disabled flag silently prevents activation.
• State flapping despite delays. DelayOnMs / DelayOffMs delay the state transition, not the condition check; values hovering near a threshold can still flip repeatedly without adequate deadband or hysteresis.
• Context fields missing. Any extra fields you want shown alongside the triggering value must be declared in the behavior's context configuration; undeclared fields will not appear in the alarm display.
• Deadband ignored. Deadband applies only to numeric comparisons. For custom logic, supply a HysteresisExpression.
• Performance. SeverityMapping expressions run on every value change; overly complex or looping expressions can degrade performance.
• Shelving is temporary, not a mute. Shelving expires (15m–24h). Over-using it defeats the purpose of monitoring.
• Borders reserve space. RowBorderColor: transparent removes the visible border, but the app still reserves 2px so row heights do not shift.
• Flash applies narrowly. FlashRate: 0 disables animation; the breathing animation only applies to unacknowledged alarms in the Active state, and stops on hover for readability.
• Display rule vs. persistence. DisplayRule affects only table visibility, not state; the alarm is still tracked even when hidden.
• Responsibilities resolution. Responsibility names may take a moment to appear the first time they are shown while the UI looks them up.
• Notes are plain text. HTML and markdown are not supported; input is sanitized on display.
• Filter resets focus. Changing any filter resets pagination to page 1, and a selected alarm loses focus when the table re-renders.
• Mobile is limited. The mobile card layout omits some columns (duties, time range filters); use the desktop view for full feature access. An "Acknowledge All" button is available for bulk operations on mobile.