Alarm, command and notify blocks

These blocks act on people and devices: they open and close alarms, send commands, answer a device’s own requests and send notifications. The alarm and command blocks need a message whose originator is a device; Notify works on any message.

Raise alarm

Opens an alarm on the message’s device, or updates the open one of the same type: one open alarm per device and type.

Setting	Meaning	Default	Values
alarm	The alarm type	required	a template, e.g. tank.{{ msg.metadata.topic }}.low; letters, digits, _ . : -, at most 128 after rendering
severity	Severity	warning	critical, major, minor, warning, info
text	Title	the type	a template, at most 256 characters
value	Kept in the alarm’s details	msg.payload	a path
notify_to	Who is told	nobody	user ids, e-mail addresses, the roles OWNER, ADMIN, USER
notify_channels	Channels	each person’s choice	channel ids such as inapp, mail
notify_min_severity	Tell only from this severity	info	a severity
notify_repeat_sec	Remind while open and not acknowledged	no reminder	0, or 60 seconds and more

out: the alarm (msgType alarm, the alarm in msg.payload). Errors: not_a_device, bad_alarm_id. Notifications follow the same lifecycle as alarm rules: throttling, a digest in an alarm storm, critical alarms bypass personal preferences unless your organisation turned that off. An escalation notifies again; a re-raise at the same severity does not. A late message changes no alarm. See Alarm notifications in depth.

Clear alarm

Resolves the open alarm of a type on the message’s device.

Setting	Meaning	Values
alarm	The alarm type	required, a template

out: the cleared alarm, or the message unchanged when none was open. Whoever was told about the alarm is told it was resolved.

Acknowledge alarm

Acknowledges the device’s open alarms: they stay open, reminders stop.

Setting	Meaning	Default	Values
alarm	Which alarms	every open alarm	*, a type, or a prefix ending in *
min_severity	Only from this severity	info	a severity
note	A note on each alarm’s timeline	none	at most 256 characters

All three alarm blocks produce alarms exactly like alarm rules do. An alarm change they make is heard by Device message triggers listening to alarm; a flow that raises an alarm and also listens to alarms may start itself again, and the deploy warns “May start its own flow again”. See Working with alarms.

Send command

Sends a command from the device profile’s command list to the message’s device. Nothing waits: the message goes on with the request it made; the device’s answer arrives later.

Setting	Meaning	Default	Values
command	A command of the profile’s command list	required (or a raw method)	picked from your profiles’ commands
params	The command’s parameters	none	an object such as {"on": true}, or a path such as msg.payload
method	A raw method outside the command list	empty	namespace.verb, at most 64 characters

out: the message with msg.metadata.rpcId (the request, also on the device’s Commands tab) and msg.metadata.rpcStatus (QUEUED, or FAILED when the command could not wait and the device was offline). Errors (no request was made):

Code	Meaning
not_a_device, device_not_found	Not one of your devices
unknown_command	The device’s profile has no such command
bad_params	The parameters do not match the command (msg.error.param names one)
method_refused	A factory reset, pairing or forgetting the network is never sent from the cloud
limit	Too many commands to this device in the last minute (default 30 from flows)
device_not_active, rpc_not_supported_by_profile, payload_too_large	As the console would say

• The command is looked up in the profile of each message’s device: a flow serving several profiles sends only to those whose profile has the command.
• The request is made as the flow and appears in the device’s command history like one from the console. A high-impact command needs no confirmation when it runs: it was confirmed at deploy.
• Deploying needs the send permission of the command’s level in every profile that has it, Deploy flows with control-level nodes for a high-impact command, and the raw-RPC permission for a raw method.
• A replayed or redelivered message finds the request it already made and sends nothing again. A late message sends no command.
• Each request ends with one rpc_response message (SUCCESSFUL, FAILED, TIMEOUT, EXPIRED, CANCELLED) with msg.metadata.rpcStatus, rpcId and requestedBy. It is a device message, so it reaches the device’s root flow; route it from there.

Commands to devices behind a gateway are in development. See Sending commands to devices.

Answer device request

Answers a request the device sent to the platform (an rpc_request message: the device calls a method on the cloud). The built-in methods getCurrentTime and getSessionLimits are answered before a flow sees anything.

Setting	Meaning	Default	Values
result	What the method returns	msg.payload	any value; sent as {"ok": true, "result": …}
error	Refuse instead	none	unsupported_method, bad_params, busy, timeout, expired, forbidden, payload_too_large, internal; sent as {"ok": false, "error": …}
message	Text sent with a refusal	empty	at most 256 characters, templates allowed

The first answer wins. When no flow answers within 5 seconds, the platform answers unsupported_method. Errors: rpc_request_closed, not_an_rpc_request, payload_too_large, invalid_value. An MQTT device gets the answer on v1/rpc/up/res/{id}, an HTTP device on its waiting request. Put this block on the rpc_request branch of the root flow (the default root only logs these requests).

Notify

Sends a notification and passes the message on.

Setting	Meaning	Default	Values
Recipients	Rows of a Kind and a value	required	at most 20 rows; 20 recipients after expansion
Repeat reason	What makes two notifications “the same” for the cooldown	the words of the notification	template, 200 characters
Channels	Restrict to these channels	each recipient’s preferences	channel ids such as inapp, mail, sms, push
Urgency	critical skips personal preferences unless your organisation turned that off	normal	normal, critical
Title, Text	The message		templates, 200 and 4,000 characters
Text format	text, or html for mail	text	text, html
Mail subject, Reply to	Mail options	the title, none	templates
Copy, Hidden copy	More mail recipients; each gets their own mail	none	templates
Mail attachments	Files for the mail	none	10 files, 1 MiB together

Who is reached, on which channel

Kind	Value	Reaches
user	A member’s user id	That member, in the app, by push and in linked chat apps
role	OWNER, ADMIN or USER	Every active member with that role, as above
custom_role	A custom role key	Its members, as above
team	A team id	Its members, as above
originator_owner	Empty	The owners of the message’s originator, where a module declares them, as above
address	One or more e-mail addresses, comma-separated	E-mail
phone	One or more numbers in international form, comma-separated	SMS

Members are passed by their user id only. E-mail and SMS reach only the address and phone rows. A member listed as a user, or reached through a role, custom role or team, gets the notification in the app, by push and in linked chat apps according to their preferences, but not by e-mail or SMS, even when they have an e-mail address. To mail people, add their addresses in an address row.

A role or team with more than 20 active members is refused (too_many_recipients) rather than half-told.

Cooldown, quotas and late messages

• A person gets a notification of the same reason from the same flow once per 10 minutes (your plan may set another, at least 1 minute). Set Repeat reason when the text changes with every reading, for example level of {{ msg.metadata.deviceName }}. The next notification after the cooldown ends with “(+n)”.
• Before sending, the block checks the monthly mail and SMS quotas; a channel out of quota is left out (msg.metadata.notify.quota). Only when every channel is out does it fail with limit.
• A late message notifies nobody.

out carries msg.metadata.notify: recipients, delivered, failed, suppressed, invalid, quota, held. Errors: no_recipients, too_many_recipients, members_unavailable, invalid_attachment, notify_failed, node_not_ready, circuit_open, limit.

See Notifications from rules and flows for templates, HTML mail and attachments.