Automation starters

A starter is a ready-made alarm rule or automation with a few fields to fill in: the parameters it reads or writes, limits, times and who is notified. It builds an ordinary document that opens unsaved in the alarm rule form or the automation editor, where you review it, dry-run it and save it; nothing is created before you save. After that it is your document: change it like any other, and later changes to the starter do not touch it.

To use one, see start from a starter.

Names and messages are built in every language of the app, with the Name you enter in them as written. When you save without changing a text, it keeps all its languages.

Alarm rule starters

Threshold alarm

Raises an alarm when a number parameter stays above or below a limit.

Field	Meaning
Name	Names the rule (Tank level: above limit) and starts its message
Parameter	A parameter of number type
Alarm when the value is	Above or below the limit
Limit, Hysteresis	The alarm clears once the value is back past the limit by the hysteresis (0 by default)
Raise after, Clear after	How long the value must stay past the limit, and back within it (60 s and 30 s)
Severity	Warning by default
Keep until acknowledged	Latching
Notify, Notify after	Recipients, and how long notifications wait (nobody, 0 s)
Alarm when unknown for	Optional: raise the rule’s separate unavailable alarm when the value stays unknown this long

Builds an alarm rule with the input value, calculated limit (and clearLimit with hysteresis), the condition value > limit or value < limit, and the message {label}: {value}, above the limit of {limit} with the value rounded to two decimals. Inputs are read as often as the workspace allows, at least every 10 s.

When values are unknown (stale, failed reads, disabled parameter) the alarm is neither raised nor cleared. Only Alarm when unknown for reports that, with a separate alarm.

Communication loss alarm

Raises an alarm when an endpoint stays disconnected.

Field	Meaning
Name	Names the rule (Boiler PLC: no connection) and starts its message
Endpoint	The endpoint to watch
Raise after	How long it must stay disconnected (2 min); shorter drops raise nothing
Severity	Urgent by default
Keep until acknowledged, Notify, Notify after	As for the threshold alarm

Builds an alarm rule on the endpoint’s connection (not connected) that clears as soon as the endpoint reconnects, with the message {label}: no connection and how long it has been disconnected.

When the connection state is unknown, such as while the endpoint’s connector is offline, the rule’s unavailable alarm is raised after the same time.

Automation starters

Escalate an unacknowledged alarm

Notifies more people when nobody acknowledges an alarm rule’s alarm in time.

Field	Meaning
Name	Names the automation (Tank overflow: escalation) and starts its message
Alarm rule	The rule whose alarm is watched
Escalate after	How long the alarm may stay unacknowledged (15 min, up to 24 h)
Escalate to	Recipients (owners and admins by default)
Severity	Urgent by default
Stop when the alarm clears	On by default; turn it off for a latching alarm that must be acknowledged even after it clears

Builds an automation that reads the alarm’s state, not its transitions: the inputs active and unacknowledged ("state": "unacknowledged"), and the calculated waiting, which is active and unacknowledged (just unacknowledged when Stop when the alarm clears is off). A branch held on waiting for the delay sends {label}: not acknowledged for {delay}.

Failure behavior: acknowledging (or clearing) the alarm before the delay sends nothing, however fast the alarm changes, because the end of the wait reads the alarm as it is then. A notification already sent stays sent. One notification is sent per wait; the next waits until the alarm is raised and unacknowledged again. The wait runs only while the automation is enabled: disabling or deleting it stops the escalation, and enabling it forgets waits from before. Besides alarm changes, the alarm is checked every delay, so an alarm already raised when you enable the automation starts its full wait at the next check.

Scheduled setpoint

Writes a setpoint at times of day, every day or on chosen weekdays.

Field	Meaning
Name	Names the automation (Office: setpoint schedule)
Setpoint	A writable parameter of number type
Schedule	1–10 entries: time, weekdays (none chosen: every day), value
Write the current value when enabled	On by default

Two entries cannot share a time on a day they both have.

Builds an automation with a timeOfDay trigger for each entry, in the workspace timezone. Each runs one procedure, apply, that writes the value of the entry that fired last at that moment, so a time that runs late, such as one caught up after a restart, never brings back an older entry’s value. With Write the current value when enabled, onInit runs apply too, so the setpoint is right before the next time comes.

Failure behavior: a write that fails or that the device refuses is not repeated and shows in the run’s steps; the setpoint stays as it is until the next entry. Writes are limited to two a minute. While the automation is disabled nothing is written, and times missed by more than two minutes are skipped.

Duty/standby alternation

Runs one of two to four units (pumps, fans, compressors) at a time, hands duty to the next unit on a schedule, and fails over when the duty unit fails.

Field	Meaning
Name	Names the automation (Booster: duty/standby) and starts its messages
Units	2–4, in duty order: a writable Run command (boolean or number), optional Running feedback and Fault (boolean or number)
Switch duty at, Switch on weekdays	When duty moves to the next healthy unit (06:00, every day)
Fail over after	How long the duty unit may report a fault or not report running (60 s)
Severity	Of failover notifications; warning by default
Notify about failovers	Optional recipients

Each unit needs its own run command.

Builds an automation that keeps the duty unit in the state variable duty (1 for the first unit). Its run command gets true or 1, and the others false or 0; the new duty unit is started before the others are stopped. Commands are written when the automation is enabled, at the switch time, and on failover.

• A unit is healthy while its fault input is known and clear and its running feedback is known, on or off; a unit with neither is always healthy. The duty unit fails while it is not healthy, or while its running feedback is not on.
• Once the duty unit has failed for Fail over after, the next healthy unit in order takes over, the members chosen under Notify about failovers are notified, and the failover is logged in the run history. The new duty unit then gets the same time to report running.
• When no other unit is healthy, the duty unit keeps running and the urgent alarm {label}: unit {from} failed, no standby available is raised. Until then every check tries the other units again, so one that recovers takes over; the alarm clears once the duty unit, whichever it is by then, works. Enabling the automation again while the failure lasts raises it again.
• At the switch time, duty skips units that are not healthy; with none, it stays. The new duty unit’s wait to report running starts at the next check.

Unknown values count as a failure: a unit whose fault or feedback is unknown is not trusted to take over. Besides input changes, the units are checked every Fail over after, or the workspace’s shortest trigger interval when that is longer, because a value that becomes unknown triggers nothing by itself. A unit with neither feedback nor fault is never failed over. A write that fails is not repeated. Writes are limited to three per unit a minute, within the workspace’s writes per minute; a workspace that allows fewer writes a minute than there are units cannot save it, since a switch cut short would leave two units running.

Daily summary

Sends chosen members the current values of up to nine parameters at a time of day.

Field	Meaning
Name	Names the automation and starts the message title
Send at	08:00 by default
Weekdays	None chosen: every day
Send to	Recipients (owners and admins by default)
Values	1–9 rows: a label and a parameter of any type

Builds an automation with a timeOfDay trigger that sends an information notification {label}: daily summary with one label: value line per row; numbers are rounded to two decimals.

Failure behavior: the inputs are read every 10 minutes, so a value can be up to about 20 minutes old. A value that is unknown shows as a dash, and the summary is still sent.

API

Starters are in the templates.automation procedures of the API; every member can read them, and the assistant uses them too.

Procedure	What it does
templates.automation.list	Starters (id, kind, name, description, summary), filtered by kind (automation or alarmRule) and query
templates.automation.get	One starter with its placeholders in form order
templates.automation.instantiate	Builds the document from values; saves nothing

A placeholder has a name, a kind, a label and optional help, optional, bounds and default. Values are keyed by name:

Kind	Value
parameter	A parameter id; valueTypes and writable say which parameters fit
endpoint, alarmRule	An endpoint or alarm rule id
number	A number within min and max
duration	Milliseconds within min and max; forms show them in unit (s, min, h)
timeOfDay	"HH:MM"
weekdays	ISO weekdays, 1 for Monday to 7 for Sunday; [] for every day
severity	info, warning or urgent
recipients	{ "kind": "roles", "roles": […] } or { "kind": "members", "userIds": […] }
boolean	true or false
choice	The value of one of options
text	Plain text of up to maxLength characters, saved as written
list	An array of minItems to maxItems rows, each keyed by the names of fields

A value left out takes the placeholder’s default; an optional one without a default is left out of the document. A placeholder with shownWhen (name and optional values) counts only while the placeholder it names has one of those values, or any value: otherwise forms hide it, and its value is neither required nor used. A list may name its rows with itemLabel. instantiate returns { ok: true, kind, document, diagnostics }, where diagnostics are the validator’s against the workspace, or { ok: false, problems }. Each problem has a JSON pointer path into values (/limit, /entries/1/time), a code and args:

Code	Meaning
required, invalid, unknown_placeholder	Missing, malformed, or not a placeholder
out_of_range (min, max), too_few (min), too_many (max)	Outside the bounds
duplicate	Repeats an earlier row, such as one time on one day
parameter_not_found, parameter_type (expected, actual), parameter_not_writable	The parameter does not fit
endpoint_not_found, alarm_rule_not_found, member_not_found	Not in the workspace

Save the document with automation.create or alarmRule.create. An unknown starterId is automation_starter_not_found.