Skip to main content

Alert Rules That Follow Device Timers

Feature entitlement: alertsManagement ยท Plan: ๐Ÿ‘‘ Pro Device Plan or higher

Introductionโ€‹

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.

info

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. 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 alertRuleUid for the next steps. Get Alert Rules lists your rules with their UIDs.

  2. 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. 3

    Send it back with the setting turned on

    Send the same periodicity with followDeviceTimers set to true, 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 [].
  4. 4

    Check the rule

    Read the rule again. Its periodicity now contains the setting:

    "periodicity": { "interval": 600, "activeTimeWindows": [], "followDeviceTimers": true }
warning

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 timeThe display's timers sayDoes the rule check the display?
07:59Off since 20:00 yesterdayNo
08:00 to 08:04On, for less than 5 minutesNo
08:05 to 19:59OnYes
From 20:00OffNo

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โ€‹

SituationWhat happens
The device has no timers set, or all its timers were clearedThe rule checks it at any hour.
The device's timers only have off timesThe rule never checks it. With no on time, the device counts as off all week.
The device's timers only have on timesThe rule checks it at any hour, except for 5 minutes after each on time.
Native and Proprietary Timers disagreeThe device counts as off when either of them says off.
An on time and an off time fall on the same minuteOff wins.
Proprietary Timers keep the device connected while its display is offThe rule still skips the device while its timers say off, whatever the rule's condition is.
The rule also has active time windowsThey are ignored while the rule follows device timers.
The rule has a % of devices thresholdOnly the devices that are on are counted.
A device that is already in an open alert turns offIt 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 offNo new alert is raised, and open alerts stay as they are.
You change a device's timersThe rule uses the new timers once the device has reported them.
A device stops reportingThe rule keeps using the timers that the device reported last.
A device hasn't reported a valid timezoneIts 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 onAn 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 as Periodicity 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.