Note: Sometime in the first half of 2023 this template will be updated to only support JS Scripting and use openhab_rules_tools.
Frequently one wants to do something when one or more Items exceed or fall below a certain threshold; for example sending an alert message or taking remedial actions.
This rule is triggered by the state of a Group. The Group should be of type Number and have a suitable aggregation function to change the state of the Group in a meaningful way. For example, if the rule is to generate an alert when battery Items get below 25%, the Group should be Group:Number:Min so the rule triggers when ever the minimum of all the battery levels changes.
Of course the trigger can be modified after a rule is created to change the trigger if needed, e.g. change to using a member of trigger instead.
When the rule triggers it compares the state of the Group using the selected comparison and value. If the comparison passes the rule is called.
Inside the rule all the members of the Group that are NULL or UNDEF are collected as well as all those that match the comparison. These are passed as attributes to a user selected script.
nullItems: a java.util.List collection of all the Items in the Group that are NULL or UNDEF.
nullItemLabels: a String with all the
nullItemslabels listed, separated by commas.
threshItems: a java.util.List collection of all the Items in the Group that match the comparison.
thresItemLabels: a String with all the
threshItemslabes listed, separated by commas.
To access these attributes in your called script use
context.getAttribute("name");, for example
One more check is performed. To avoid lots of alerts there is a rate limit that causes the script to be called no more often than the amount of time defined (e.g. “24h”). This can be as long as days or as short as milliseconds.
Finally, there is an optional do not disturb period that can be defined. Set the “Do Not Disturb Start Time” and “Do Not Disturb End Time” parameters with the hour and minute of the day defining when the script should not be called. When an event occurs during that time period, the script will be called at the end of the time period. When the end time is before the start time, the do not disturb period is treated as spanning midnight (e.g. a start time of 22:00 and end time of 08:00 will go from 22:00 today through 08:00 tomorrow).
When the start and end times are the same no DND period is applied so only the rate limit applies.
An example use case would be to generate an alert with the labels from all your battery Items that are below 25% but send this alert no more than once a day and wait until 07:00 if the alert occurs after 22:00. To implement that:
- Create an AllBatteries Group:Number using MIN as the aggregation function.
- Add all the battery level Items to this Group.
- Create a script with the actions to take when one or more batteries fall below the given level. For example, send a notification, send an email, flash a light, etc.
- Instantiate the template and populate the properties selecting the Group, setting the threshold, selecting the comparison, the rate limit (how long to wait before calling the script again), the script to call that implements actually sending the alert (coded by you), set the do not disturb start time to 22:00 and the end time to 07:00.
- Only number Items are supported
- A script to call when one or more Items fail to match a comparison.
- A Group containing all the Items to trigger this rule.
- The Group should be a Group:Number:X where X is a meaningful aggregation.
- If on OH 4+ Nashorn must be installed separately or change the script type to
- See Open Reminder [3.3.0;3.4.9) for a rule template that handles Switch and Contact Items.
- adjusted for breaking change, will no longer work for versions of OH prior to December 15th
- Made compatible with Nashorn and JSScripting
NOTE: Will drop support for Nashorn sometime after OH 3.2 release.
- If an alert occurs during DND, when the end of DND occurs don’t call the script if no longer outside of the threshold.
- Fixed the check for the do not disturb time when that time spans midnight
- Fixed problem with parameters
- added support for a do not disturb period
- initial release