Rules

Rules turn events into outcomes. Each one reads as a sentence: WHEN an event arrives from the sources it listens to, IF its conditions hold, THEN its actions run, OTHERWISE other actions run. Rules are evaluated the moment an event arrives and, for conditions about time passing, every 30 seconds.

Anatomy of a rule#

WHEN: the trigger#

The trigger narrows which events the rule listens to. Choose its type, then filter.

IF: the conditions#

IF is a list of conditions that must all hold, with optional any of groups. The Advanced canvas adds nested logic, counting, sequences and sustained conditions (below). A rule with no conditions fires on every event its trigger matches.

THEN and OTHERWISE: the actions#

THEN lists the actions that run when the conditions hold; OTHERWISE lists those that run when a matching event arrives but the conditions fail. Each action has a policy for when it runs: on a new incident only (the default for notifications, so a flapping sensor does not send a mail per reading), on every event (the default for state changes) or when the incident resolves.

Conditions#

The editor offers 27 kinds of condition in five groups, plus the logic group below. Clock marks a condition that is also checked on the timer, so it can become true without any event arriving. Canvas marks one that only the Advanced canvas offers.

Sensors

Time

Incidents

People

Variables

Combining conditions#

The logic group combines conditions. Groups nest on the canvas, and a rule the form cannot show opens on the canvas by itself.

Actions#

A rule has 12 kinds of action. Actions run in order; a failure in one never stops the others.

E-mail and webhooks#

• E-mail needs outbound mail configured (Notifications:Smtp). Without it, rule e-mails are skipped with a warning. A mail links back to the incident through AppBaseUrl.
• Webhooks make an HTTP request (GET, POST or PUT) with your headers and body. Calls go to public addresses only: private, loopback and link-local addresses are refused unless you allow them with Webhooks:AllowedHosts or Webhooks:AllowPrivateAddresses; redirects are not followed and a call times out after 10 seconds. Resolved addresses are pinned, so a name cannot be swapped for a private address in between.
• Both accept templates: {{incident.id}}, {{incident.rule}}, {{incident.sensor}}, {{incident.person}}, {{incident.domain}}, {{incident.severity}}, {{incident.confidence}}, {{incident.triggeredAt}}, {{incident.value}}, {{incident.unit}}, {{event.type}}, {{event.nature}}, {{event.severity}}, {{event.source}}, {{event.value}} and {{event.at}}. Values placed in a JSON body are escaped so they cannot break out of their field.
• E-mail and webhook calls are queued and delivered in the background, so a slow mail server never delays the ingest of events.

Variables#

Set variable and Clear variable maintain named values shared by every rule of the organisation: a flag such as “armed”, or a counter with increment and an optional expiry. The Variable and Variable number conditions test them. They are how one rule tells another what it saw.

Operating devices#

Operate device sends a command to an output: one output, every output of a kind at the event's place, or a zone and the zones inside it. Optionally it lasts for a number of minutes, after which the previous state is restored. Sensitive outputs such as locks, door strikes and sirens may be operated by a rule because rules are trusted. A rule never re-triggers itself through the state change its own command causes. See Devices.

Arming a place#

Arm place and Disarm place arm or disarm an arming profile of a place, the Profile armed condition tests it, and the Arming change trigger starts a rule when a profile is armed, disarmed or refused. They are not the Arm zone and Disarm zone actions, which send a command to an alarm panel's integration URL. See Arming.

Incidents from rules#

Create incident opens an incident or adds the event to the one that is ongoing for the same source and domain. Three settings on the rule shape the result:

• Grouping. One incident per sensor or person, per place (so several sensors in one place corroborate each other and raise confidence), or one for the whole organisation.
• Auto-resolve after N minutes without a new event, so a quiet incident closes by itself.
• Resolve when the source restores. A door closes, a panel zone restores, a sensor comes back online, a limit is back inside: the incident closes. For a rule that starts on a schedule, the end of the schedule resolves it, which is how a rule gets a fresh incident each day.

Keeping the noise down#

• The Cooldown condition keeps a rule from firing again within N minutes of its last firing, and Daily limit caps how often it fires in a day (in your time zone).
• Notify at most every N minutes (per source) skips e-mails and webhooks inside the window while the incident itself keeps updating.
• Grouping by place and the default new incident only policy mean a burst of readings becomes one incident and one mail.
• Each firing is recorded, and the rules list shows when each rule last fired.

Building and testing#

• Form. The default editor, laid out as WHEN, IF, THEN, OTHERWISE and Settings, with a one-sentence summary of the rule that updates as you edit.
• Advanced. A node canvas for nested logic, with zoom, fit and automatic layout. It is not keyboard-navigable; the form is the accessible path.
• Test. Replays recent stored events (the last hour, 6 hours, 24 hours or 7 days; up to 40 events) through the rule as it is on screen, unsaved. For each event it shows which conditions passed or failed and how many events would have fired the rule. Nothing is saved, sent or operated. For a schedule trigger it replays the schedule's switches instead.
• List. The rules page has search, an enabled filter and toggle, and flags a rule without conditions and actions as needing attention. Viewers see rules read-only.

Worked examples#