Scheduling

From Documentation
Jump to: navigation, search

This feature allows you to automate repeated tasks or set tasks to run at the specified time, or times.

WSchedule.png

Here are some examples of what you can do via the scheduling feature:

  • run the task at 9:15 am every day
  • run the task every 15 minutes
  • run the task on Wednesdays and Sundays every week at 5:00 pm
  • run the task tomorrow at 9:30 am, only once
  • run the task every month on the 1st, 7th, 14th and 21st at 9:00pm, but not on the weekends (do not run the task on Saturdays and Sundays)
  • ... and many more

The list above is just an example and you can set up the software to follow almost any schedule you need.

How does it work?

The scheduling algorithm is based on a set of rules. Each rule is either a Trigger or an Exclusion. You can specify unlimited number of rules, and the scheduling algorithm will check them one by one to determine when to start the task. In most cases, you will only need one Trigger rule to tell the scheduler when your task should be started. In more complex scenarios, you can use multiple Trigger and Exclusion rules.

Triggers

Triggers define when and how often a task is to be run. Triggers can be of the following types:

  • Hourly trigger - schedules a task to run every hour at the specified minutes (for example, every hour at 15 and 45 minutes)
  • Daily trigger - schedules a task to run every day at the specified hours and minutes (for example, every day at 8:00 am and 5:30 pm)
  • Weekly trigger - schedules a task to run every week on the specified days (for example, every week on Mondays and Wednesdays at 9:00 am)
  • Monthly trigger - schedules a task to run every month on the specified days (for example, every month on the 3rd, 15th and 22nd at 10:00 pm)
  • Yearly trigger - schedules a task to run every year on the specified months (for example, every year on the 1st of April and July, at 3:00 pm)
  • Run-Once trigger - schedules a task to run only once at the specified fixed date and time (for example, today at 4:45 pm)
  • Interval trigger - schedules a task to run over fixed time intervals (for example, every 32 minutes, every 3 days etc.)

Custom trigger

In addition to the simple triggers explained above, we implemented universal trigger to give you even more control over the scheduling. Custom trigger works similarly to the Cron system. Here you can manually specify time frames, define periods and even use tokens/keywords. Custom trigger works with the following time frames:

  • years;
  • months;
  • days;
  • weekdays;
  • hours;
  • minutes.

You can set each time frame either to "any" or to specific value (or values).

  • The "any" setting means that the scheduler will ignore this time frame (i.e. if the year is set to "any" - it means that the task is allowed to run in the current year or in the any of the following years, without any limits).
  • If the time frame is set to a specific value - the scheduler will allow the task to run only when that value matches current date/time. For example, if the Minute(s) is set to 15 and all other time frames to "any" - the task will run every hour, exactly at 15 minutes. Another example: if the Hour(s) is set to 9, the Minute(s) to 15 and all other time frames to "any" - the task will run every day, at 9:15 am.
  • If the time frame is set to multiple values (separated by commas) - the scheduler will run the task when any of the values match current date/time. For example, if the Minute(s) is set to 15,30,45 and all other time frames to "any" - the task will run 3 times every hour: at 15, 30 and 45 minutes.

For each time frame that is not set to "any", all time frames below it also must not be set to "any". For example, if you specify 9 for Hour(s), you also need to specify something for Minute(s), otherwise the software will not be able to compute the time to run the task at.

Each time frame has the following restrictions:

  • years - must not be lower than the current year (as there is no sense in trying to schedule the task in the past) and must not exceed current year+100;
  • months - must be between 1 and 12 (inclusive);
  • days - must be between 1 and 31 (inclusive);
  • weekdays - must be between 0 and 6 (inclusive), where 0 stands for Sunday and 6 - for Saturday;
  • hours - must be between 0 and 24 (inclusive), the values for Hours must be in the 24 hours format (i.e. 9 pm is expressed as 21);
  • minutes - must be between 0 and 59 (inclusive);

Additionally, you can use functions and expressions in the fields. You can learn more about this feature in the Randomization section. The expression must return integer number (or the list of comma-separated numbers) that are within the above ranges.

For example, if you want to run the task every day at random hours and random minutes, you can take advantage of the $randomint{...} function by setting Hour(s) field to $randomint{24} and Minute(s) field to $randomint{60} (all other fields to "any"). Basically it means that the software will compute random number in the range [0, 24) for Hours and random number in the range [0, 60) for the Minutes, and then will schedule the task for this computed time. After the task is run, the software will again compute random time and so on. Using this approach, you can get even more specific by supplying different arguments to $randomint{}. For example, if you want to run the task at random hours, but only between 8 am and 9 pm - then you need to specify $randomint{8, 22} in the Hour(s). The second argument in this example is set to 22 because the $randomint function never includes upper bound in the set of generated random numbers, so $randomint{8, 22} will generate random numbers between 8 and 21 inclusive.

Exclusions

Sometimes you would want to exclude certain times from the schedule. Suppose you want the task to run every day at 9:00 am and 3:00 pm, but only on the workdays (skip weekends). With triggers alone, it would not be so easy to set up such a schedule. That's where exclusions come in handy. You set up a daily trigger for 9:00 am and 3:00 pm o'clock, and then set up a days-of-the-week exclusion for Saturdays and Sundays. Now, if the trigger wants to fire on weekends, the exclusion will cancel it. But, if the trigger fires on workdays, the exclusion will do nothing.

Much like triggers, exclusions can be of different types to conveniently exclude certain time ranges to from the schedule:

  • Exclusion for the specific time interval - you can specify an exact time period to exclude from the schedule. For example, you can prevent triggers from firing at any time between 1/1/2012 6:00 am and 3/1/2012 5:00pm. This type of exclusion takes two parameters - starting date and ending date. If you specify both dates, the interval is said to be closed and if a trigger fires within this interval - it will be cancelled by the exclusion. You can also specify only one of the dates (ether starting date or ending date). In this case, the interval is said to be open. If only the starting date is specified and a trigger fires at any time after the starting date - it will be cancelled by this exclusion. Likewise, if only the ending date is specified and a trigger fires at any time before the ending date - it will be cancelled by this exclusion.
  • Exclusion for minutes of any hour. This one allows you to cancel a trigger that fires at the exact minute or minutes. For example, you can set the exclusion to cancel a trigger that wants to run a task between 10 and 15 minutes of any hour.
  • Exclusion for hours of any day - allows to cancel a trigger that fires at the exact hour or hours. For example, you can set the exclusion to cancel a trigger that wants to run a task between 2 am and 4 am.
  • Exclusion for weekdays of any week - allows to cancel a trigger that fires at the exact day (or days) of the week. For example, you can set the exclusion to cancel a trigger that wants to run a task on Saturdays and Sundays.
  • Exclusion for days of any month - allows to cancel a trigger that fires at the exact day (or days) of the month. For example, you can set the exclusion to cancel a trigger that wants to run a task on the 13th day of any month.
  • Exclusion for months of any year - allows to cancel a trigger that fires at the exact month (or months) of the year. For example, you can set the exclusion to cancel a trigger that wants to run a task on February of any year.

Just like with triggers, you can combine exclusions to build the schedule of the desired complexity.

Exclusions can also be local and global.

  • Local exclusions apply only to the specific trigger, that is said to be the parent of such an exclusion. Local exclusion cannot cancel a trigger that is not its parent. Local exclusions appear right below their parent trigger in the list of rules, and they are indented to show their belonging to the parent. In order to add local exclusion, you need to select a trigger and click "Add exclusion" button. New exclusion will have the selected trigger as its parent.
  • Global exclusions apply to all triggers above it in the list. For example, if you have 3 triggers in the list and one global exclusion following them (in this particular order), no matter which of the 3 trigger fires - the exclusion may cancel any trigger. Global exclusions appear on the same level with the triggers in the list, without indentation. In order to add global exclusion, all triggers in the list must be un-selected


The rules in the schedule (both triggers and exclusions) are applied in the same exact order that they appear in the list. For example, if you have trigger #1, a global exclusion, and then trigger #2 following it, then the exclusion will only work for the trigger #1. Should trigger #2 fire within the time frame that falls within the excluded range, it will not be cancelled by the exclusion (because it comes before trigger #2).

When multiple triggers are added to the schedule, the one that fires first will start scheduled task.

Example. 
Right now is Monday, 7:00am. 
You have a schedule with 2 triggers: 
 1. daily trigger for 9:00am 
 2. weekly trigger for Mondays, 8:00 am. 
The second trigger will be the one to start the task, because it fires before the first one 
(The first trigger fires at 9:00am, but the second one - at 8:00am, because today is Monday).

Additional features

  • Misfire policy lets you define the behavior of the scheduling algorithm for the tasks that were not run at their scheduled times for whatever reason.
  • Start scheduling and Stop scheduling boxes let you define the time frame to limit execution of your tasks. For example, if you set up the scheduler to run the task every day at 6:00am, it will continue doing so indefinitely. Suppose, you want to run the task every day at 6:00am, but only in July, 2012. You can achieve that by specifying the 1st of July, 2012 in the Start scheduling box and the 31st of July in the Stop scheduling box. You can also use only one of the boxes. For example, specifying Start scheduling date without the Stop scheduling date means Run the task at its scheduled times, but after that date. If you set the Stop scheduling date, but leave the Start scheduling box empty, it would mean Run the task at its scheduled times, but not after that date
  • Time zone box lets you specify the time zone for all times that you input in this scheduler window and set for the scheduling rules. It may be useful if you operate a computer in a remote location, with a different time zone, and you don't want to convert the times manually. For example, if your current time zone is UTC-5 (Eastern Standard Time) and the computer is in the UTC-8 (Pacific) time zone, you can use your native EST times to schedule the tasks and specify "UTC-05:00" in the Time zone box. The software will convert all your times to the Pacific time zone automatically
  • Simulation is a feature that allows you to verify the setup of your schedule. It shows when exactly the task will be run in accordance with the schedule