Scheduled Rule Examples

Pierre Kil edited this page Nov 15, 2016 · 12 revisions
Clone this wiki locally

This page contains additional examples of scheduled rules using the 'cron' syntax. It assumes you've already read page Controller Rules to understand the basic rule notation.

The six and seven parameter cron format can be used for relatively complex scheduling tasks although still not completely eliminating the need of calendars when irregular scheduling is required. Expressions such as "At 10:00 AM every Monday through Wednesday", "At 3 PM and at 6 PM on Mondays from June to August" or "On every last Monday of the month at 6 PM" can be expressed with cron.

Cron expressions can also become difficult to understand fairly quickly. Therefore this page contains some common examples for simple use cases with cron expressions. At the end of the page the full cron expression specification is included.

Heartbeat Interval

The example below shows a simple 'heartbeat' interval defined with cron that executes every 15 minutes, every day. It will execute a shell script command defined with the shell execution protocol.

package org.openremote.controller.protocol

global org.openremote.controller.statuscache.CommandFacade execute;
global org.openremote.controller.statuscache.SwitchFacade switches;

rule "Heartbeat Every 15 Minutes"

  timer (cron: 0 0/15 * * * ?) when eval (true) then

  execute.command("My Shell Script"); 

end

For more details, see Cron Expression Minute Increments.

Gradual Light Brightness Increase at Wake Up

The example below shows a gradual brightening wake-up behavior scheduled for each morning during 7:00 AM to 7:30 on weekdays but not on Saturdays and Sundays. The light level is increased by one step on every minute. The day-of week-range '2-6' corresponds to MON-FRI, Sunday considered the first (number 1) day of the week and Saturday the last (number 7). Notice that when the day-of-week range is used, the '?' character (meaning no value) must be used for the day-of-month field.

Example provided by Jani Kahrama.

package org.openremote.controller.protocol

global org.openremote.controller.statuscache.CommandFacade execute;
global org.openremote.controller.statuscache.SwitchFacade switches;

rule "Sunrise"

  timer (cron: 0 00-30 7 ? * 2-6)

when eval(true) then

  execute.command("bedroom_dim(UP)", 1);

end

For more details, see Cron Expression Minute Ranges and Day of Week Range.

Day of Week Range

Example below demonstrates use of range for day-of-week field. It schedules a telnet based commands for VLC media player to start at 7:10 AM on every morning except on Saturdays and Sundays.

The day range is expressed with numbers, where the first (number 1) day of the week is Sunday and the last day (number 7) of the week is Saturday. The range value '2-6' corresponds to MON-FRI. Notice that when the day-of-week range is used, the '?' character (meaning no value) must be used for the day-of-month field.

Example provided by Jani Kahrama.

package org.openremote.controller.protocol

global org.openremote.controller.statuscache.CommandFacade execute;
global org.openremote.controller.statuscache.SwitchFacade switches;

rule "Waketune"

  timer (cron: 0 10 7 ? * 2-6)

when eval(true) then

  execute.command("Input CD");
  execute.command("Volume10");
  execute.command("VLC_play");

end

Gradual Volume Increase at Wake Up

Example below demonstrates combination of distinct time values (separated by comma character) with time ranges. It sets up a schedule of increasing volume on weekdays (Monday to Friday) starting at 7:12:10 AM and continuing until 7:32:40 AM in 30 second increments. The increments are configured by setting distinct second values '10,40' for the time range starting from 7:12 minutes and ending at 7:32 minutes.

The day range is expressed with numbers, where the first (number 1) day of the week is Sunday and the last day (number 7) of the week is Saturday. The range value '2-6' corresponds to MON-FRI. Notice that when the day-of-week range is used, the '?' character (meaning no value) must be used for the day-of-month field.

Example provided by Jani Kahrama.

package org.openremote.controller.protocol

global org.openremote.controller.statuscache.CommandFacade execute;
global org.openremote.controller.statuscache.SwitchFacade switches;

rule "Waketune_volup"

  timer (cron: 10,40 12-32 7 ? * 2-6)

when eval(true) then

  execute.command("Volume Up");

end

Cron Expression

Cron expressions have six mandatory fields and an optional seventh field (year) separated by white space. A cron expression therefore follows the format:

Scheduled Rule Examples - Cron Expression

Seconds

Valid value: 0-59, *

See Minutes on how to specify values - same expression rules apply.

Minutes

Valid value: 0-59, *

An individual minute value can be provided (e.g. '15' or '25'). Distinct minute values can be separated with commas. An asterisk ('*') character can be used to represent 'any' minute value.

Scheduled Rule Examples - Minutes

Minute Ranges

A range of minutes can also be provided, using '-' character. Minute ranges can also overflow to the next hour if a larger value is defined on the left-hand side of the range (see examples below). Note that if multiple ranges are specified (for example for both minutes and hours) then the overflow behavior is unspecified.

Scheduled Rule Examples - Minute Ranges

Minute Increments

Increments are defined with '/' character. The first value is the initial time, the second value represents the increment. Note that the increments do not flow over -- therefore specifying 30/35 will only trigger at the first 30 minute mark, but not every 35 minutes after that.

Scheduled Rule Examples - Minute Increments

Hours

Valid value: 0-23, *

See Minutes on how to specify values - same expression rules apply.

Day of Month

Valid value: 1-31, L, ?, *

An individual day of the month value can be provided (e.g. '15' or '25' for the 15th and 25th day of the month). Distinct day of the month values can be separated with commas. An asterisk ('*') character can be used to represent 'any' day of the month value.

IMPORTANT NOTE: when any value other than '?' (meaning no value) is specified in this day-of-month field, a 'no-value' character '?' must be specified in the sixth 'day-of-week' field. Similarly, when any 'day-of-week' value is specified in the sixth field of the cron expression, this 'day-of-month' field must contain character '?', no other value is allowed. Failure to follow these rules will cause the rule deployment to fail.

For last day of the month rules, see Last Day of Month.

Scheduled Rule Examples - Day of Month

Day of Month Ranges

A range of days in month can also be provided, using '-' character. Day-of-month ranges can also overflow to the next month if a larger value is defined on the left-hand side of the range (see examples below). Note that if multiple ranges are specified (for example for both day-of-month and month) then the overflow behavior is unspecified.

Scheduled Rule Examples - Day of Month Ranges

Last Day of Month

Last day of the month in the 'day-of-month' field can be denoted with 'L' character. This way the last day of the month can be chosen regardless of the length of the month, as shown below.

Scheduled Rule Examples - Last Day of Month

Day of Month Increments

Increments are defined with '/' character. The first value is the initial day of the month the rule is executed (assuming the when conditions are true) and the second value represents the increment of days until next time the rule is evaluated for execution.

Note that the increments do not flow over and only apply for the month specified - therefore configuration 15/20 will only trigger at the 15th day of the month while the 20 day increment falls outside of that day-of-month range.

Scheduled Rule Examples - Day of Month Increments

Month

Valid value: 1-12 or JAN-DEC

Day of Week

Valid value: 1-7 or SUN-SAT

Year

Valid value: 1970-2199

Scheduled Rule Examples - Year

See Also