Rules and Alerts

Rules (called workflows in the UI) turn raw telemetry into action: email a group when a sensor crosses a threshold, set a device's alert state, or fire a downlink. This page covers the parts that are specific to you as a partner, authoring across a whole product line, shipping templates, and deciding what your sub-accounts can build. The hands-on builder reference (triggers, conditions, branching, actions, modulators, testing) is shared with your customers and lives in the end-user guide; this page links into it rather than repeating it.

note

Where to find it: Sidebar -> Operations -> Workflows, or a Device Profile -> Workflows tab for profile-scoped workflows.

Scopes: where a workflow applies

A workflow is a small graph of connected nodes (Trigger -> Conditions -> Actions). For how to build one, see Creating workflows. What's partner-specific is scope, you can author at seven levels:

Scope	Applies to	Authored from
Device profile	every device on that profile	Operations -> Workflows (blank, or cloned from a template); templates from Device Profile -> Workflows tab
Device	one specific device	Operations -> Workflows
Site	every device at one of a sub-account's sites and the sites nested under it (needs Multi-site and sub-account-scope workflows on that sub-account's tier)	Operations -> Workflows
Sub-account	devices within one sub-account	Operations -> Workflows
Gateway	one specific gateway	Operations -> Workflows
Site gateways	the gateways at one of a sub-account's sites and the sites nested under it (same tier requirements as Site)	Operations -> Workflows
All gateways	every assigned gateway you manage (or, authored while acting as a sub-account, that account's assigned gateways)	Operations -> Workflows

From partner level you pick the sub-account first and then one of its sites; the Site select locks when that sub-account's tier lacks Multi-site or sub-account-scope workflows. A site workflow follows the hierarchy downward: a workflow on a top-level site covers everything under it, a workflow on a child site covers that child and what is nested under it. Equipment with no site is not covered. The builder mechanics are in the shared reference: What you can build.

Profile scope is the most useful: it's how you say "every thermometer in this product line alerts when it gets too hot" once, instead of per device. The field picker on a profile-scoped workflow offers that profile's fields. Your PARTNER profiles are partner-side authoring only; a customer whose plan includes rules.allowSubAccountProfileRules can author profile workflows on their OWN customized profile copies (clones), which only ever fire on their own devices. A customer can also make their own version of one of your profile workflows for their devices, or remove it from their account; see What customers can do with your profile workflows.

The notification bell shows your workspace's own alerts. A customer's workflows, and your workflows set to Customers with these devices, notify the customer whose device it is; act as the account to see those. Each workflow's fire log stays visible from the Workflows list either way.

At partner level the inbox has a scope filter: All for this workspace; (your workspace name) only, which is devices not assigned to an account plus the SMS credit pool notices; and About (account name), which is your own alerts concerning that account: Workspace team only alarms on its devices, its out-of-credits notice and its closure request. An account's own alerts show when you act as that account. For platform operators: while acting as an account, the bell shows only that workspace's alerting workflow notifications on the account's devices, while Fleet and the widgets show what the account sees, so the two do not match by design.

Gateway scopes watch gateway health instead of telemetry: a gateway going offline, or losing line power (see Power source). They are notify-only in this first version - email, SMS, and webhook actions fire once per incident and recover automatically, with nothing in the notification bell and nothing to acknowledge - and the all-gateways scope picks up newly assigned gateways with no per-gateway setup. The builder mechanics are in the shared reference: Gateway workflows.

Ownership: who can change a workflow

Every workflow belongs to the side that created it. Author one at partner level and it stays partner-managed: the sub-account whose devices it watches can see it (marked as managed by your workspace) but cannot edit, disable, or delete it. The one exception is a profile workflow: a customer's Workspace Admin can save their own version of it for their devices, or remove it from their account, which is covered below. Author one while acting as a sub-account (the "Act as" action on Sub-accounts) and it belongs to that account, exactly as if their own admin had built it.

Ownership is fixed at creation and works both ways: from partner level you cannot edit a customer-owned workflow either. The workflow list shows an Owner column, and customer-owned rows carry an Open in ... shortcut that switches you into that account and opens the workflow there. To narrow the list by owner, use the account filter next to the search box: All accounts, your workspace only (workflows created at partner level), or a single sub-account.

Two practical consequences:

• If you want a customer to manage the alerting on their own devices, create the workflow while acting as their account (or let them build it, see the tier features below).
• A workflow may only send email or SMS to notification groups within its own scope: workflows you author at partner level use your partner-level groups; a workflow owned by a sub-account, whether their admin built it or you did while acting as that account, picks from that account's own groups only. A partner-managed profile workflow fires across many customers, so you cannot attach per-customer groups to it yourself. A customer who wants their own recipients saves their own version of the workflow, which uses their groups.

Device lifecycle housekeeping happens automatically: when a device is unassigned, transferred, claimed by another account, moved to a different profile, or deleted, its active alarms clear (with the reason recorded in the alarm history and an alarm.cleared webhook), and any device-scope workflows owned by an account the device just left are disabled with an audit entry - they would otherwise keep firing with no one able to manage them. The same applies to site workflows: when a device or gateway leaves a site workflow's sites (moved to another site, detached, its network moved, or a site reparented or deleted), that workflow's alarm on it clears with reason device_moved; see Webhooks for how to tell a site move from an account exit on the payload. A site cannot be deleted while a workflow is scoped to it. Closing a sub-account also removes its workflows, mutes, notification groups, and inbox entries.

How often a workflow notifies

Every run that passes its gates runs its actions. A reading arrives, the conditions pass, and the workflow's actions execute. The human-facing sends (email, text, in-app, webhook) go out up to the workflow's Max fires / hr per device; downlinks and status changes run on every pass. Pacing beyond that is authored, and three things pause or limit the human-facing sends:

• Acknowledging the alarm (ack-until-recovery): acknowledging a device's alarm is the operator's explicit "seen it, stay quiet until it is actually over." Email, text, in-app rows, and the alert chip pause for that workflow + device while the condition stays true; downlinks and multi-casts keep running. When the condition recovers, the alarm closes normally (recovery email included); the next trip is a new alarm and notifications resume in full. The pause is visible on the device's Status widget with a Resume notifications undo, and it cannot outlive its alarm: if a workflow's condition stays quiet on that device for 24 hours, the episode is treated as over and the next trip notifies in full (readings that keep the condition active count as activity even when a schedule window or throttle is holding the actions back). Disabling a workflow also resets any pause; the disable confirmation shows how many active alarms it will clear and offers a 24-hour snooze as the gentler alternative (see Saving, switching on, and pausing).
• Max fires / hr, per device. A workflow that leaves the field blank gets the platform tier's default, 1 repeat notification per device per hour (rules.maxFiresPerHourDefault), and no workflow can set more than the ceiling, 12 by default (rules.maxFiresPerHourCap). Once a device has fired that many times in the rolling hour, further notification sends stop, while downlinks, multicasts, and the device's alert status keep running; the first fire of a new alarm is never suppressed. It's per device on purpose: one flapping sensor can't starve a profile-scope workflow for every other device. Suppressed runs show as throttled in the fire log; workflows are never disabled automatically. The end-user mechanics are in Creating workflows.

Deliberate pacing is the Throttle node - a positional pass limiter that lets readings through its branch at most once per window (see Modulators in the end-user guide). Note the cost dimension: a texting workflow with no throttle sends one text per recipient per matching reading, and every text consumes SMS credits.

• Recovery is judged on the conditions, not the calendar. A workflow recovers only when every one of its field conditions is present on a reading and evaluates false; readings that simply omit the field, and closed Schedule windows, never count as recovery, so alternating frame types can't flap alarms.
• Recovery delay damps flapping. The workflow's Recovery delay setting holds the alarm open until the conditions have stayed clear for that long; on top of that, an alarm always stands at least 60 seconds after its last run before it can auto-recover.
• Recovery emails (the per-workflow toggle, plan-gated) send once per recovery, to the combined recipients of every email node on the workflow.
• Offline workflows run for devices and gateways. Workflows with a time-since-reading condition under a periodic trigger are evaluated by a platform sweep every few minutes. A silent device notifies on the first sweep pass that finds it silent; later passes in that hour are capped by Max fires / hr, so at the default the first hour is one notification. The moment it reports again, the alarm recovers. Gateway offline (and power) monitoring lives on the gateway scopes and notifies once per incident instead of every pass; the old device-workflow "gateway last stats" condition never evaluated, is no longer accepted on save, and any legacy workflow still carrying it stays inert until it is recreated as a gateway-scoped workflow (the condition panel offers a one-click switch back to watching the device).

Sub-account-scope workflows now fire

Sub-account-scope workflows are evaluated on every uplink from the account's devices (they previously could be created but never ran). The rules.allowSubAccountScope tier feature gates a CUSTOMER authoring their own account-wide workflows; you can always create one at partner level (it stays partner-managed) or while acting as the account (it becomes theirs).

Because an account's fleet usually spans several device types, account-wide field conditions are limited to the universal fields: Signal Quality, RSSI, SNR, Battery, and the semantic fields (Temperature (°F), Humidity (%), and so on). A semantic condition uses the field each device's own profile tagged with that semantic, so it applies only to devices whose profile carries the tag; the rest never satisfy it. Any other device-type-specific reading belongs on a device or profile scoped workflow, where the field is guaranteed to exist. A condition-free account-wide workflow (fire on every reading) is also valid.

Battery conditions compare against the device's latest known battery level (see the battery reading for where it comes from). They are evaluated on every uplink like other conditions, and additionally the moment a fresh network battery reading arrives, so a sharp drop alerts without waiting for the device's next uplink.

Alert visibility and per-account mutes

A partner-managed workflow's alarms and notifications go to the customer whose device fired it: the customer gets the notification, the fleet alarm, and the Status widget chip, and can acknowledge it (acknowledge clears the alarm for everyone and records who did it). Your workspace sees that workflow's alarms only on devices not assigned to an account. Its email and text actions already go only to your own notification groups, so who on your side hears about a fire is a per-workflow choice, not a flood by default. To watch a customer device yourself, run a second workflow set to Workspace team only, usually with its own thresholds. Two controls tune this:

• Alert visibility (on the workflow, workspace-level authors only): Customers with these devices (the default) shows alarms and notifications to the account each device is assigned to, and to your workspace only for devices not assigned to an account. Workspace team only keeps the workflow itself internal to your workspace: customers do not see it in their Workflows list, their notifications, fleet page or widgets, and cannot take it over or remove it. It still runs on their devices.
• Per-account mute (the customer's side): a customer admin can mute a partner-managed workflow for their account only. Your view is unaffected, and the workflow keeps running; you can see mutes in the audit log (rule.muted / rule.unmuted).

What customers can do with your profile workflows

You author a profile workflow once and it runs on every customer's devices of that profile, at your settings. You do not pick accounts and nothing on the workflow needs opening up. Each customer then manages it from their side:

• Save their own version. A customer's Workspace Admin opens your workflow, changes anything (conditions, actions, recipients, schedule, name) and saves it as their own version. From then on their devices run their version and yours stops on them. Their version is an ordinary customer-owned workflow: it lists with an Owner of that account, carries an Open in ... shortcut, and you never edit it. Your notification groups and webhooks are not carried over into it (their version uses their own groups); a Send downlink or Multi-cast action is dropped from it when the customer's plan has no downlinks.
• Remove it from their account. Your workflow stops on their devices and stays in their list, marked removed, with Restore.
• Switch back. From their version, one action deletes it and puts your version back on their devices. Deleting their version instead leaves your workflow removed for them; Restore brings it back.

The rules that hold:

• Your later edits reach only the accounts still on your version. An account with its own version keeps it until it switches back; there is no push.
• The Accounts button on a saved profile workflow lists every account with devices on the profile and where it stands: on your version, own version since a date (with Open in ...), or removed since a date. Who made the change is on the audit log.
• Workspace team only hides the workflow from customers. It still acts on their devices and alerts your team, but customers do not see it in their list and cannot take it over or remove it. Switching a workflow to Workspace team only gives it back to any customer that had removed it; a customer's own version stays theirs until they switch back. The Accounts drawer says so on such a workflow.
• Downlinks. A Send downlink or Multi-cast action on your workflow is skipped at fire time on devices of a customer whose plan does not include downlinks, and the fire log records it; the rest of the workflow still runs. The Accounts drawer marks those customers.
• Templates cannot be taken over, and a customer's version can never become a template on your profile.
• Account closure deletes the account's versions and removals.

Audit entries: rule.account_version.created and rule.account_version.discarded on your workflow, rule.removed_for_account and rule.restored_for_account (the customer's actions, on the customer's log, with the actor), and the usual rule.created, rule.updated, rule.deleted on their version.

Templates

Ship a profile with ready-made workflows. A template is a pre-authored workflow that lives on the Device Profile -> Workflows tab. From there you clone it into an active profile workflow with one click, or let a customer who authors on a customized copy of the profile (see the tier features below) start from it; the template itself stays untouched.

Per PROJECT_SCOPE §10, default templates ship disabled by default. The customer must clone, review, and enable them. This prevents an email storm on a freshly onboarded device.

Letting sub-accounts build their own workflows

By default, workflows are partner-managed: your customers see the alerts but don't author the rules. You can hand authoring to a sub-account through its customer tier. The relevant rule features in the tier feature bag are:

Feature	What it allows
rules.allowSubAccountScope	The sub-account can create workflows scoped to the whole account: sub-account scope for devices, and the all-gateways scope for their assigned gateways. Together with the tier's Multi-site feature it also unlocks the Site and Site gateways scopes; without both, those two options appear in the scope picker but locked, with a note that they are part of a higher plan. Both flags are checked on the target sub-account for every author, including you at partner level. Device-scope and single-gateway authoring on their own hardware is available to their admins regardless; each workflow is editable only by the side that created it (see Ownership above).
rules.allowSubAccountProfileRules	The sub-account can create profile-scope workflows on device profiles it owns (its customized copies). Only meaningful together with the tier's profile.allowSubAccountScope ("Sub-account device profiles"), which gates the customizing itself, plus each profile's "Sub-account cloning" setting. On a tier without profile.allowSubAccountScope, the "Device profile" scope still appears in the customer's workflow scope picker but locked, with a note that it is part of a higher plan; this is deliberate, so customers discover the feature. A customized copy's workflows only ever fire on that account's devices.
rules.allowSystemTriggers	Periodic triggers are available to author: the "device has gone quiet" sweep, and the gateway offline and gateway power workflows (which are periodic by construction).
rules.allowRecoveryEmails	A workflow can send a follow-up email when a condition recovers, not just when it trips.
rules.allowWebhook	The outbound webhook action is available.
rules.maxFiresPerHourDefault	Platform tier only. Repeat notifications per device per hour a workflow gets when its Max fires / hr is left blank; 1 by default. Never stored above the ceiling below.
rules.maxFiresPerHourCap	Platform tier only. Highest Max fires / hr a workflow can set; 12 by default. The workflow is never disabled for reaching it.
rules.allowScheduledRecalculate	The Recalculate fields trigger is available: a daily reading that keeps today()-based formula fields counting on devices that never report (see the shared reference). It runs on device, device profile, and sub-account scope workflows. Off by default on every tier; the partner tier and the sub-account tier must both carry it. The node shows locked in the builder until then.

Downlink and multicast actions follow the same downlink permissions used elsewhere (see Multi-casting). Set all of these per tier under Settings -> Sub-account Tiers; see Sub-accounts -> Setting up sub-account tiers for how the tier feature bag works and how partner-tier ceilings cap it.

Available action types

Which actions a workflow can run depends on the scope's tier. The set:

Action	Availability	What it does
Send email	Live	Emails notification groups, up to 5 individual addresses, or both.
Set device alert state	Live	Marks the device info, warning, or alert; surfaces on the device list, dashboards, and the device header.
Send downlink	Needs downlinks allowed	Sends a downlink to the device or a chosen target.
Trigger multicast group	Needs downlinks allowed	Fires a multicast group from a workflow.
Webhook	Needs rules.allowWebhook	POSTs a signed notification message to a URL on the node.

Under a Recalculate fields trigger, Send downlink and multicast actions are skipped; email, SMS, webhook, and alert state actions run.

The shared Actions reference covers authoring each one. Gateway-scoped workflows offer Send email, Send SMS, and Webhook only - the device-facing actions (status, downlink, multicast) have no meaning against a gateway and are rejected on save.

The webhook action is documented in the shared reference: per-node signing secret, optional message with variables, test send, and automatic retries. Its deliveries carry the same X-Pulse-Signature / X-Pulse-Event / X-Pulse-Delivery headers as the platform's API webhooks, so one receiver implementation verifies both; see Verifying the signature. The event type is workflow.fired; gateway-scoped workflows carry a gateway object in place of device and offer the gateway token set in the message (see Message variables). If a sub-account's tier later drops rules.allowWebhook, saved webhook nodes stop sending and the fire log records why; the workflow itself keeps validating, so nothing is lost on an upgrade back.

Notification groups

The Send email action targets notification groups, named recipient lists you manage in one place, and can also send to up to 5 individual addresses typed directly on the node (external addresses included). Groups remain the right tool for anything larger: they centralize the recipient list and give each member their own email opt-out. See Notification groups for creating groups, adding members, bounce and opt-out handling, scope, and per-tier limits.

Building a workflow: the shared reference

The mechanics below are identical for you and your customers, so they're documented once in the end-user guide:

• The builder, the canvas, connecting nodes, and the Draft / Enabled / Disabled states.
• Triggers, on uplink and periodic.
• Conditions, the operators, calibrated values, and how missing readings are handled.
• Combining conditions, outside-a-range with "is not between", chained conditions (and), and parallel conditions into one action (or).
• Branching, routing different conditions to different actions (works at profile scope too).
• Modulators, schedule, sustain, and throttle.
• The webhook action, URL, signing secret, test send, and retries. For a worked example, the recipe Send workflow alerts to Microsoft Teams walks the whole path from webhook node to a card in a channel.
• Message variables, the tokens available in email, SMS, and webhook messages.
• Monitoring, the fire log and email deliveries tabs.
• Testing a workflow.

For how customers receive and clear alerts (the notification bell, acknowledging, device alert state), see Responding to alerts.

Frequently asked

Can I author a workflow that fires for many devices but emails only once per device?

Yes. Use a profile-scoped workflow with a Throttle node. Each device keeps its own cooldown, so each fires at most once per window. Coalescing into a single email across many devices isn't supported today.

A customer changed a workflow I gave them. Can I get it back?

Templates are independent of the clones made from them, so editing a clone never touches your template. Re-cloning the template gives the customer a fresh copy. If the customer saved their own version of one of your profile workflows, nothing of yours changed: the Accounts button on your workflow shows which accounts run their own version, and Open in ... takes you to theirs. Only the customer can switch back to your version.