SolarNode Cron Job Syntax

SolarNode cron job syntax

Many tasks in SolarNode are executed as periodic jobs, the period being defined by a cron expression. This document describes the cron expression syntax used by SolarNode.

Examples

Before diving in the formal syntax of cron expressions, here are some common examples:

Expression	Meaning
0 * * * * ?	Once per minute, when seconds are at 0
0 0/5 * * * ?	Once every 5 minutes, when seconds are at 0
0 0 * * * ?	Once per hour, on the hour
0 0/15 9-17 ? * MON-FRI	Every 15 minutes between 9am and 5pm on Monday to Friday
0 0 2 1,15 * ?	The 1st and 15th of each month at 2am
0 15 10 ? * 6L	10:15am on the last Friday of every month
500	Every 500ms — if a simple whole number is specified, then it represents a millisecond interval

Formal syntax

Cron expressions define a precise repeating period at which a task should be executed. The expressions are defined by 6 required fields separated by spaces:

	Field	Values	Special
1	Seconds	0-59	, - * /
2	Minutes	0-59	, - * /
3	Hours	0-23	, - * /
4	Day of month	1-31	, - * ? / L W
5	Month	1-12 or JAN-DEC	, - * /
6	Day of week	1-7 or SUN-SAT	, - * ? / L #

The special column shows some additional values that can be used in place of a normal value:

Special	Meaning
*	Used to specify all possible values. For example, * in the minute field means "every minute".
?	Used to specify no specific value. This is useful when you need to specify something in one of the two fields, but not the other. For example, ? in the day of week fields means "any day of the week that matches the other fields".
-	Used to specify ranges. For example 10-12 in the hour field means "the hours 10, 11 and 12".
,	Used to specify a list of values. For example MON,WED,FRI in the day of week field means "the days Monday, Wednesday, and Friday".
/	Used to specify increments, or nth values within the range of possible values. For example 0/15 in the seconds field means "the seconds 0, 15, 30, and 45", while 5/15 in the seconds field means "the seconds 5, 20, 35, and 50". Specifying * before the / is equivalent to specifying 0 as the value to start with.
L	Used as a short-hand for last, but it has different meanings in each field it can be used in. For example, the value L in the day of month field means "the last day of the month". If used in the day of week field by itself, it simply means "7" or "SAT". But if used in the day-of-week field after another value, it means "the last xxx day of the month". For example 6L means "the last friday of the month". You can also specify an offset from the last day of the month, such as L-3 which would mean "the third-to-last day of the month". When using the L option, it is important not to specify lists or ranges of values, as you'll get confusing/unexpected results.
W	Used to specify the weekday (Monday-Friday) nearest the given day. For example 15W in the day of month field means "the nearest weekday to the 15th of the month". If the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify "1W" as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not 'jump' over the boundary of a month's days. The W character can only be specified when the day-of-month is a single day, not a range or list of days.
LW	The L and W characters can be combined for the day of month expression to specify "the last weekday of the month".
#	Used to specify "the nth" XXX day of the month. For example, the value of 6#3 in the day of week field means "the third Friday of the month" (day 6 = Friday and "#3" = the 3rd one in the month). If you specify #5 and there is not 5 of the given weekday in the month, then no firing will occur that month. The # character cannot be used with an expression list.

Randomized seconds

By default SolarNode will randomize the cron seconds field if it is a plain integer value. This is to help spread the reading of many data sources across a given minute to avoid timeouts that might occur when reading from slow network connections, like a serial port.

For example, imagine you configure a cron expression of 0 * * * * *, which literally means "run every minute at exactly 0 seconds after the minute" (that is, at the start of each minute). SolarNode will re-write the schedule with a random second field value when it schedules the job, so it might end up like 13 * * * * *, which means "run every minute at 13 seconds after the minute".

If you would like to disable the second-level field randomization, just configure a repeating second field value, like 0/60 * * * * *. That literally means "run every minute repeating every 60 second interval after the minute. Effectively that gives you the original 0 * * * * * schedule. You can spread multiple jobs across time manually by adjusting the repeating offset, like 5/60 * * * * * would effectively mean 5 * * * * *.