Write and debug automations

You need the editor, admin, or owner role: only they see Setup. Automations are in Setup → Automations (/workspace/$workspaceId/setup/automations), and alarm rules are on its Alarm rules tab. The document format is in the automations reference, and the pages are described in workspace pages.

You can also ask the assistant, for example “raise an urgent alarm when the tank level stays above 90% for 5 minutes, and notify the owner if nobody acknowledges it in 15 minutes”. It builds the alarm rule and automation, checks them, shows the dry run, and saves each one after you approve it.

Start from a starter

A starter is a ready-made alarm rule or automation, such as a threshold alarm, a scheduled setpoint or duty/standby alternation, with a few fields to fill in. The automation starters reference describes each one.

1. On the Automations tab or the Alarm rules tab, select From a starter. The starters listed make what that tab lists.
2. Choose a starter, then fill in its fields: the parameters, endpoint or alarm rule it uses, its limits and times, and whom it notifies. Fields marked Optional may stay empty. Lists, such as the entries of a schedule, have Add and a trash button for each entry.
3. Select Continue. Fields with problems are marked, such as a parameter of the wrong type or one that cannot be written.
4. The result opens unsaved: an automation in the editor, an alarm rule in its form. Review it, try an automation with a dry run, and save it. Until you save, nothing is created.

Write an automation

1. Select New automation. The editor opens with a small automation that writes a log line every minute.
2. Edit the JSON document. Tab takes the selected suggestion or indents; press Esc, then Tab, to move on to the next control. Problems are marked in the text as you type and listed under Problems; select one to go to it. Formula problems mark the part of the formula.
3. Let the editor write for you. Suggestions appear as you type, or with Ctrl+Space: the fields and kinds that fit where you are, whole steps and triggers, and in formulas the variables, functions and operators. In a field that takes a parameter, endpoint, alarm rule, automation or member, type part of its name, mnemonic or branch and choose it; the editor puts in its ID. Each ID shows the name of what it refers to, and pointing at a name, function or field shows what it is, with a Docs link. On a touch screen, tap it instead.
4. Fix problems with the actions under each one in Problems or in its mark: a nearby ID or name, a missing field, an allowed value. Ask the assistant opens a chat with the problem written for you to send. F12 or Ctrl+click on a variable or procedure goes to where it is declared, and on an ID opens it in Setup in a new tab. Go to… above the editor jumps to a trigger, variable or procedure.
5. Check Steps per run: the most steps one run of each procedure can take, against the workspace’s limit. Workspace limits shows the limits an admin or the owner set.
6. Optional: pick the Dashboard that owns the automation. A dashboard edits what it owns, and deleting the dashboard deletes it.
7. Fix every error, then select Create automation. A new automation is enabled; to disable it, use the switch in the page header.

Texts written in several languages, for example by a template, show in your language. When you save, a text you did not change keeps all its languages, and a text you changed is stored as you typed it.

Try it with a dry run

1. Under the editor, choose the procedure to run.
2. If a Telegram command runs the procedure and you want its reply steps to answer, select As a Telegram command.
3. Select Dry run. The document runs as it is in the editor, saved or not, and changes nothing.
4. Read the result: the input values, with unknown for stale or unavailable values; every step in order, with the branch each if took or why none did, the values set and written, and log lines; Would do, the writes, notifications, alarms, and replies a real run would make; and the state before and after. Writes marked over the limit would be dropped by the write limits.
5. To go to a step in the editor, select its location.

What a dry run reads and returns is in dry runs.

Read the run history

1. Open the automation’s Run history tab. Runs are listed newest first.
2. To see only failures, select Failed only.
3. Open a run to see the input values it started with, its steps with their values and branches, log lines, and writes that were dropped or that the device refused.

How long runs and their steps are kept is in how automations run.

Write an alarm rule

1. On the Alarm rules tab, select New alarm rule.
2. Under Rule, enter the name, description, and severity, set how often the inputs are read, and optionally pick the owning dashboard.
3. Under Inputs, add a name for each value the condition and message use, and choose what it reads: a parameter, whether an endpoint is connected, whether an alarm is active or not acknowledged yet, or a formula over the other inputs.
4. Under Condition, set when the alarm is raised and how long the condition must hold first, when it clears, whether it stays active until acknowledged, and when to raise a separate alarm for inputs that stay unknown.
5. Under Message, write the title and text, set the parameters that fill {name} in them, how long notifications wait, and who is notified: members with chosen roles, or chosen members by name.
6. Fix the problems shown under the fields, then save.

Formula fields suggest the inputs, functions and operators as you type, and show what a function takes while you write its arguments.

Alarm rules have no run history. The alarms they raise and clear are in the alarm log; see Alarms.

Escalate an unacknowledged alarm

The escalation starter builds this for you. To write it yourself, notify someone else when an alarm stays raised and unacknowledged for a time:

1. Add two alarm inputs for the alarm rule: active, and unacknowledged with "state": "unacknowledged".
2. Add an inputChange trigger on both that runs a check procedure, and make check the onInit procedure, so an alarm already raised when you enable the automation counts too.
3. In check, add an if with a branch on active and unacknowledged, held for the escalation time (heldForMs) and run once, that sends the notify step.

{
  "triggers": [{ "kind": "inputChange", "inputs": ["active", "unacknowledged"], "run": "check" }],
  "variables": [
    {
      "kind": "input",
      "name": "active",
      "source": { "kind": "alarm", "alarm": { "alarmRuleId": "…" } }
    },
    {
      "kind": "input",
      "name": "unacknowledged",
      "source": { "kind": "alarm", "alarm": { "alarmRuleId": "…" }, "state": "unacknowledged" }
    }
  ],
  "procedures": [
    {
      "name": "check",
      "steps": [
        {
          "kind": "if",
          "key": "escalate",
          "branches": [
            {
              "when": "active and unacknowledged",
              "heldForMs": 900000,
              "once": true,
              "steps": [
                {
                  "kind": "notify",
                  "recipients": { "kind": "roles", "roles": ["owner"] },
                  "severity": "urgent",
                  "message": { "title": "Alarm not acknowledged for 15 minutes" }
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "onInit": "check"
}

When the alarm is acknowledged or cleared, the condition stops holding and the wait ends, so the notification goes out only if nobody acknowledged the alarm in time. The branch reads the alarm as it is, so the order in which runs come cannot mislead it. For a latching alarm that must be acknowledged even after it clears, hold on unacknowledged alone.