Timer Schedule¶

Timer's frequency is determined by a JSON object assigned to the frequency property. For example, the following declaration sets the timer's frequency as 'weekly' which will be repeated every week on Mondays.

frequency: {
    schedule: 'weekly',

    repeat: {'every':1,'on':[2]}
  }

The 'frequency' JSON object has the following properties:

Property name Required Data Type Description

schedule

Yes

String

Defines how frequently the timer should run. Possible values are:

'once' - the timer will run only one time.

'daily' - the timer will run on daily basis, repeated every XX number of days set by the repeat property.

'weekly' - the timer will run on weekly basis, on the specified days, repeated every XX number of weeks.

'monthly' - the timer will run on monthly basis, on the specified months, dates, or days of the week.

repeat No JSON Object Defines how frequently the timer execution should be repeated. The structure of the object varies depending on the value set in the schedule property. See the table below for details.

The repeat property is a JSON object. The structure of the object varies depending on the value of the schedule property:

schedule property value	repeat object syntax	Description
'once'	Does not apply.	Repeat object must not be present.
'custom'	{ 'every':NUMBER }	`NUMBER` is the number of seconds between each execution of the timer. For example: `{'every':100}` - indicates that the timer should execute every 100 seconds. `{'every':5}` - requests the timer to run every 5 seconds. The highest possible value is 86400 seconds. The lower limit of the allowed values depends on the billing plan: Free plan - 60 seconds Backendless Plus - 5 seconds Cloud Enterprise - 1 second
'daily'	{ 'every':NUMBER }	`NUMBER` is the number of days between each execution of the timer. For example: `{'every':1}` - indicates that the timer should execute every day. `{'every':5}` - requests the timer to run every 5 days.
'weekly'	{ 'every':NUMBER, 'on':[1,2,3,4,5,6,7] }	`NUMBER` is the number of weeks between each execution of the timer. Numbers in the `'on'` array indicate the days of the week when the timer should run - all are optional, but at least one must be present. 1 indicates Sunday, 2 - Monday and so on. For example: `{'every':2, 'on':[2,5]}` - requests the timer to run every 2 weeks (every other week) on Monday (2) and Thursday (5).
'monthly'	{ 'every':[MONTHS ARRAY], 'on': { 'days':[DAYS ARRAY], 'weekdays': { 'on':[WEEK ASSIGNMENT], 'weekdays':[1,2,3,4,5,6,7] } } }	`MONTHS ARRAY` is a numeric array of numbers representing months when the timer should run. 1 stands for January and 12 is for December. For example: 'every'``:[1,3,11] indicates that the monthly timer should run every January, March and November. Once the months when the timer runs are established, the 'on' property is used to set the detailed schedule. There are two mutually exclusive options: `'days'` and `'weekdays'`. If one is set, the other one must be `null`. `DAYS ARRAY` is a numeric array of days on which the timer should run. 1 represents the first day of the month, 31 stands for the 31st. For example: `'days':[1,5,10]` indicates that the timer must run on the 1st, 5th and 10th days of the selected months. `WEEK ASSIGNMENT` is an array of week indicators with possible values: `'first'`, `'second'`, `'third'`, `'fourth'` and `'last'`. These values are used in combination with the `'weekdays'` property which is an array of numbers. The numbers in the `'weekdays'` array indicate the days of the week when the timer should run - all are optional, but at least one must be present. 1 indicates Sunday, 2 - Monday and so on. For example: `'weekdays':` `{` `'on':['first', 'last'],` `'weekdays':[1,3,7]` `}` requests the monthly timer to run on the first and last Sunday, Tuesday and Sunday of the months from the `MONTHS ARRAY`.
'cron'	{ 'every': STRING }	A cron expression is a string `'* * * * * *'`, which consists of 6 mandatory and 1 optional fields that represent a specific time pattern. Cron fields accept INT, special characters, names of days and months.

Cron Timer¶

Cron is a job scheduler that allows running specific tasks periodically at fixed times, dates or intervals. Cron relies on the UNIX-timestamp, that represents a counter that was initiated on January 1st, 1970 at UTC. It counts time in seconds from the initial to the current time. For more information refer to the official cron scheduler documentation.

Important

Support for cron-scheduled timers is available in applications in Backendless Cloud on the Cloud99 plan and above as well as Backendless Pro and Managed Backendless.

A cron expression is a string '* * * * * *', which consists of 6 mandatory and 1 optional fields that represent a specific time pattern. Cron fields accept INT, special characters, names of days and months.

For instance, the following expression will run a task every hour, 5 minutes and 10 seconds every day, since the fourth argument that corresponds to a day of a month * wasn't specified:

{  
  'every': '10 5 1 * * *'  
}

Here is the illustration on how passed values correspond to the argument's actual position:

Position	Field	Mandatory	Values	Special Characters
1	Second	Yes	0-59	, - * /
2	Minute	Yes	0-59	, - * /
3	Hour	Yes	0-23	, - * /
4	Day of a month	Yes	0-31	, - * ? / L W
5	Month	Yes	1-12 or JUN, JUL, AUG	, - * /
6	Day of a week	Yes	0-7 or MON, TUE, WED	, - * ? / L #
7	Year	No	1970-2099	, - * /

Note, that 0 and 7 in 'day of a week' field represent Sunday, while other days start with 1 and further.

Special characters can be used to granulate time patterns:

Special Character	Description
*	Used to select all values within argument's range. For instance, all days within a week or month.
?	This character represents no value, but it is useful when it comes to two similar arguments like 'day of a week' and 'day of a month'. When you want to run a task on every Wednesday, then by using `?` character in the 'day of the month' field, the cron will ignore that field and will only use the 'day of a week'.
-	Used to specify ranges, for example 3-10 in the minutes field represents all minutes separately in that range.
,	Allows choosing a set of values in one single field. For instance, 'WED, THU, FRI' will be the days that cron takes into account to run tasks.
/	Increment character that specifies two values before and after the slash: range/step-size. The argument with values 3-59/5 will run a task at 8, 13, 18 and further.
L	Represents the last day of a week or a month. If used in the 'day of a week' field as `5L` , when the month value is set, then it will represent 'the last Friday of a specific month'.
W	Very useful when you need to specify the nearest business day, while ignoring weekends. When `10W`is set in the 'day of a month' field, and if the 10th day of the month is Saturday, then cron will run a task on the nearest business day which is Friday 9th. And if the 10th is Sunday, then the task will be executed on Monday 11th.
#	Used to select a specific day of the week or month. When `5#3` is set in the 'day of a week' field, then cron will run a task on Friday the third week of the month. In situations when cron is set to run a task on Friday the fifth week of the month which is `5#5`, and there's no such a day in that month, then the cron will not run anything.

Create a Cron Timer¶

To create a cron timer in the Backendless UI, go to'Cloud Code -> Timers' and click on the 'New Timer' button. Then fill out required fields, set the cron expression without single quotes ( e.g. 10 5 1 * * * ) and click on the 'SAVE' button.

cron_timer_creation_example1