app-notification

Description

The app-notification block is used to send push notifications to users' mobile applications. The notification title and message are defined in the block configuration, and their fragments may be filled with current values delivered from tag blocks.

The block has no outputs. To work correctly, it requires at least one connection from a block other than tag, which will trigger an attempt to send the notification.

The block stores the last values received from tag blocks, the number of successfully sent notifications, and information about the last sending error or the reason why sending was blocked.

Configuration parameters

Parameter name	Value
`send_to_all`	Required boolean parameter with values `true` or `false`. When set to `true`, the notification is addressed to all users that have an email address associated with the account. When set to `false`, the recipients are selected using the `send_to` parameter.
`send_to`	Required parameter when `send_to_all = false`. Contains a comma-separated list of user logins. Invalid entries are filtered out. If no valid login remains after filtering, the configuration is invalid.
`send_uncompleted_messages`	Required boolean parameter with values `true` or `false`. When set to `false`, the block will not send a notification if at least one placeholder from `title` or `message` has not yet received a value from the corresponding `tag` block. When set to `true`, such a notification may be sent, and missing placeholders are replaced with the `{?}` text.
`block_repeated_values`	Required boolean parameter with values `true` or `false`. When set to `true`, the block will not send another notification if the full title and full message are identical to the last successfully sent notification.
`high_priority`	Required boolean parameter with values `true` or `false`. Defines whether notifications sent by this block should be marked as high priority.
`title`	Required parameter. Defines the notification title. The value must not be empty. The text may contain placeholders in the `{X}` form, where `X` is the tag number, for example `{1}` or `{2}`.
`message`	Required parameter. Defines the notification body. The value must not be empty. The text may contain placeholders in the `{X}` form, where `X` is the tag number.

Input handling

The block allows multiple input connections.

Two kinds of signals are supported at the input:

values coming from tag blocks, used to fill the {X} placeholders in title and message
the value true coming from a block other than tag, which triggers an attempt to send the notification

Other signals from blocks other than tag, such as false, numbers, text, or null, are ignored.

Values received from tag blocks are stored as the last value for the given tag number. When inserting them into the title and message, the textual representation of the value without the unit is used. If the received value cannot be represented as text, that change does not update the stored tag value.

The block supports dynamic inputs labeled using the tag block:

Input number and name	Description
`tagX`: Value inserted into `{X}`.	Every `{X}` placeholder used in `title` or `message` must have a corresponding connected `tag` block with number `X`. At the same time, every connected `tag` block must be used at least once in `title` or `message`.

An attempt to send a notification after receiving the value true works as follows:

the full content is built from title and message by inserting the last received tag values
if send_uncompleted_messages = false and at least one tag value is missing, the notification is not sent
if send_uncompleted_messages = true, missing values are replaced with the {?} text
if block_repeated_values = true and the full title as well as the full message are identical to the last successfully sent notification, sending is blocked
if no recipient email address can be determined, sending also does not take place

The block requires at least one connected trigger source, which means a block other than tag. Connections coming only from tag blocks are not enough for a valid configuration.

Block outputs

The block has no outputs.

Block status description

For a correctly operating block, the status description has one of the following forms:

Notifications sent: X.

or:

Notifications sent: X, last error: Y

where:

X means the number of successfully sent notifications
Y means the last error or the reason why sending was blocked

The last error field may indicate, among others:

missing complete tag values when send_uncompleted_messages = false
an attempt to send the same notification again when block_repeated_values = true
missing recipient email addresses
an error returned by the notification sending mechanism

Errors returned by the block

The block can return the following errors:

Error code	Error description
`Missing parameter 'send_to_all'.`	The `send_to_all` parameter was not provided in the configuration.
`Missing parameter 'send_to'.`	The `send_to_all` parameter is set to `false`, but the `send_to` parameter was not provided in the configuration.
`Empty 'send_to' parameter.`	The `send_to` parameter was provided, but it is empty.
`No valid users specified.`	After invalid entries were filtered out from `send_to`, no valid user login remained.
`Missing parameter 'send_uncompleted_messages'.`	The `send_uncompleted_messages` parameter was not provided in the configuration.
`Missing parameter 'block_repeated_values'.`	The `block_repeated_values` parameter was not provided in the configuration.
`Missing parameter 'high_priority'.`	The `high_priority` parameter was not provided in the configuration.
`Missing parameter 'title'.`	The `title` parameter was not provided in the configuration.
`Empty title.`	The `title` parameter is empty.
`Missing parameter 'message'.`	The `message` parameter was not provided in the configuration.
`Empty message.`	The `message` parameter is empty.
`Missing {X} in title or message.`	A `tagX` block is connected to the block, but its number is not used either in `title` or in `message`.
`Missing tagX.`	A `{X}` placeholder is used in `title` or `message`, but the corresponding `tagX` block is not connected.
`Missing non-tag block.`	No trigger source other than a `tag` block is connected to the block.

Usage examples

If title = Alarm in {1}, message = Temperature reached {2}, tag1 is connected with the last value Kitchen, tag2 is connected with the last value 28.5, and the value true arrives at the input from another block, then a notification with the title Alarm in Kitchen and the message Temperature reached 28.5 will be sent.
If message = Sensor {1}: {2}, but before sending is triggered only the value for tag1 has been received, then with send_uncompleted_messages = false the notification will not be sent.
In the same situation, if send_uncompleted_messages = true, the missing value will be replaced with the {?} text, so the message may become Sensor Living room: {?}.
If block_repeated_values = true and two consecutive sending triggers generate exactly the same title and exactly the same message, then the second notification will be blocked.
If send_to_all = false and the send_to parameter contains several comma-separated logins, the notification will be addressed only to users from that list for whom the system can determine a recipient email address.