Timer Schedule

The @BackendlessTimer annotation must be used to define timer's attributes. The annotation's argument is a JSON object represented as a string. The JSON object has the following properties:

Property name	Required	Data Type	Description
startDate	Yes	Number	Contains a timestamp when the timer must be executed for the first time. The timestamp is the number of milliseconds between the time the timer must run and midnight, January 1, 1970 UTC.
expire	No	Number	Contains a timestamp when the timer schedule is complete. No timer events will happen after the specified timestamp. The timestamp is the number of milliseconds between the time the timer schedule expires and midnight, January 1, 1970 UTC. If the parameter is missing, the timer never expires unless it is scheduled to execute only once.
frequency	Yes	JSON Object	Contains the definition of timer's frequency of execution. This is a complex data structure with a detailed explanation below (see the Timer Frequency section).
timername	Yes	String	Timer name for identification purposes. The timer will appear with the specified name in Backendless Console. The name must start with a letter, it cannot contain spaces or dashes.

Timer's frequency is determined by a JSON object expressed as a string and assigned to the frequency  attribute in the BackendlessTimer annotation. For example, the following declaration sets the timer's frequency as 'weekly' which will be repeated every week on Mondays.

@BackendlessTimer("{'startDate':1398189720000,'frequency':{'schedule':'weekly','repeat':{'every':1,'on':[2]}},'timername':'my_timer'}")
public class WeeklyTimer extends TimerExtender

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 10Wis 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.