Alert Rules That Follow Device Timers
alertsManagement ยท Plan: ๐ Pro Device Plan or higherIntroductionโ
When a display's Timers switch it off every evening, it goes offline on schedule. An Alert Rule that watches for offline devices then raises an alert every night, for a display that is doing exactly what you told it to do.
You can make an Alert Rule follow device timers. The rule then checks each device only while that device's own timers keep it on. This works for every alert type, not only for offline alerts.
You turn this on through the REST API, with the followDeviceTimers setting in the rule's periodicity. Box has no control for it yet.
How it worksโ
When followDeviceTimers is true:
- The rule checks a device only while the device's timers keep it on. While they keep it off, the device raises no alert.
- The rule reads both Native and Proprietary Timers, as the device last reported them. The device counts as off when either of them says off.
- The rule's Active time windows are ignored.
- Timers are read in the local time of each device, the same way as active time windows.
Devices with no timersโ
A device with no timers set is checked at any hour, as if the rule had no active time windows. This covers a device that has never reported timers and a device whose timers you cleared.
For example, a rule covers a display with a timer from 08:00 to 20:00 and a media player with no timers. At 23:00 the rule checks only the media player.
Turn it on for an existing ruleโ
Alert Rules are changed on behalf of a user. Use an Account token or a personal token of a user who can edit the rule in Box. A service token belongs to no user, so it can read Alert Rules but cannot create or change them: Update Alert Rule then answers 404, as if the rule didn't exist. A token of a user who cannot edit the rule gets the same answer. See REST API Authentication for the X-Auth header.
- 1
Set the rule up in Box
Create the Alert Rule and set its conditions, threshold, schedule, and target as usual. You need the rule's
alertRuleUidfor the next steps. Get Alert Rules lists your rules with their UIDs. - 2
Read the rule's schedule
Read the rule with Get Alert Rule:
curl "https://api.signageos.io/v1/alert-rule/{alertRuleUid}" \--header "X-Auth: {tokenId}:{tokenSecret}"The response contains the rule's
periodicity, for example:"periodicity": { "interval": 600, "activeTimeWindows": [] } - 3
Send it back with the setting turned on
Send the same
periodicitywithfollowDeviceTimersset totrue, using Update Alert Rule:curl -X PUT "https://api.signageos.io/v1/alert-rule/{alertRuleUid}" \--header "X-Auth: {tokenId}:{tokenSecret}" \--header "Content-Type: application/json" \--data '{ "periodicity": { "interval": 600, "activeTimeWindows": [], "followDeviceTimers": true } }'The API answers with status
200:{ "message": "OK" }The request replaces the rule's whole
periodicity, so send all of it as you read it:- Keep the rule's
interval. It is how often the rule is checked, in seconds, from 30 to 3600, and a different value changes that. Content Guard rules run every 15 minutes (900): keep that value. - Keep the rule's
activeTimeWindows. They are required even though they are ignored while the rule follows device timers, and they apply again when you turn the setting off. A rule with no windows has[].
- Keep the rule's
- 4
Check the rule
Read the rule again. Its
periodicitynow contains the setting:"periodicity": { "interval": 600, "activeTimeWindows": [], "followDeviceTimers": true }
Saving the rule's settings in Box turns this setting off, because Box saves the schedule without it. After you edit the rule in Box, send the request again.
Create a rule with the settingโ
You can also turn the setting on when you create a rule with Create Alert Rule. This needs an Account token or a personal token too:
curl -i -X POST "https://api.signageos.io/v1/alert-rule" \
--header "X-Auth: {tokenId}:{tokenSecret}" \
--header "Content-Type: application/json" \
--data '{ "name": "Offline during opening hours", "periodicity": { "interval": 600, "activeTimeWindows": [], "followDeviceTimers": true } }'
The API answers with status 201 and { "message": "OK" }. The Location response header holds the address of the new rule, which ends with its alertRuleUid.
If your account belongs to more than one company, add companyUid to the body. Without it, the rule is created in the first company of your account.
Create Alert Rule doesn't take the rule's conditions or target organizations. Set them with Update Alert Rule. If you set them in Box instead, turn the setting on again afterward.
Turn it offโ
Send the rule's periodicity with followDeviceTimers set to false:
curl -X PUT "https://api.signageos.io/v1/alert-rule/{alertRuleUid}" \
--header "X-Auth: {tokenId}:{tokenSecret}" \
--header "Content-Type: application/json" \
--data '{ "periodicity": { "interval": 600, "activeTimeWindows": [], "followDeviceTimers": false } }'
This request replaces the whole periodicity as well. Send the interval and the activeTimeWindows that the rule should use from now on. With [], as in the example, the rule is checked at any time.
A periodicity sent without followDeviceTimers turns the setting off too.
Example: a store displayโ
A display in Prague has a timer that turns it on at 08:00 and off at 20:00 every day. An Alert Rule with an offline condition follows device timers.
| Prague time | The display's timers say | Does the rule check the display? |
|---|---|---|
| 07:59 | Off since 20:00 yesterday | No |
| 08:00 to 08:04 | On, for less than 5 minutes | No |
| 08:05 to 19:59 | On | Yes |
| From 20:00 | Off | No |
For 5 minutes after a timer turns a device on, the rule still treats the device as off. This gives the device time to start and reconnect before the rule checks it.
If the timer runs only from Monday to Friday, on at 08:00 and off at 18:00, the rule doesn't check the display from Friday 18:00 until Monday 08:05. The last thing the timers did before the weekend was to turn the display off.
Check which timers a device reportedโ
The rule uses the timers that each device last reported. To see them, read the device's latest timer telemetry. TIMERS holds the Native Timers and PROPRIETARY_TIMERS the Proprietary Timers:
curl "https://api.signageos.io/v1/device/{deviceUid}/telemetry/TIMERS/latest" \
--header "X-Auth: {tokenId}:{tokenSecret}"
curl "https://api.signageos.io/v1/device/{deviceUid}/telemetry/PROPRIETARY_TIMERS/latest" \
--header "X-Auth: {tokenId}:{tokenSecret}"
A 404 answer means that the device hasn't reported timers of that type. A device that answers 404 to both requests has no timers for the rule, so the rule checks it at any hour.
Edge casesโ
| Situation | What happens |
|---|---|
| The device has no timers set, or all its timers were cleared | The rule checks it at any hour. |
| The device's timers only have off times | The rule never checks it. With no on time, the device counts as off all week. |
| The device's timers only have on times | The rule checks it at any hour, except for 5 minutes after each on time. |
| Native and Proprietary Timers disagree | The device counts as off when either of them says off. |
| An on time and an off time fall on the same minute | Off wins. |
| Proprietary Timers keep the device connected while its display is off | The rule still skips the device while its timers say off, whatever the rule's condition is. |
| The rule also has active time windows | They are ignored while the rule follows device timers. |
| The rule has a % of devices threshold | Only the devices that are on are counted. |
| A device that is already in an open alert turns off | It stays in the alert. It leaves the alert once it is on again and no longer matches the condition. |
| Every device of the rule is off | No new alert is raised, and open alerts stay as they are. |
| You change a device's timers | The rule uses the new timers once the device has reported them. |
| A device stops reporting | The rule keeps using the timers that the device reported last. |
| A device hasn't reported a valid timezone | Its reported UTC offset is used instead, and if it hasn't reported that either, UTC. |
| A device needs more than 5 minutes to start and reconnect after its timer turns it on | An offline rule can raise an alert for it. The device leaves the alert once it reconnects. |
Errorsโ
followDeviceTimers accepts only true or false. Any other value, including null, is rejected with status 400:
- Update Alert Rule answers
INVALID_FIELD_TO_UPDATE_ALERT_RULE, with a detail such asPeriodicity followDeviceTimers is not a boolean: "yes". - Create Alert Rule answers
INVALID_BODY_PROPERTIES.
An interval outside 30 to 3600 seconds, or a periodicity without interval or activeTimeWindows, is rejected with status 400 too.