Custom Scheduling
=================

Overview
--------

Swivel uses a specific scheduling syntax for several of its jobs. On most screens, they are in a user-friendly format with a drop-down menu, but they may still be customised for specific requirements. This document covers the customised format.

Custom Scheduling
-----------------

A cron expression is a string comprised of 6 or 7 fields separated by white space. The 6 mandatory and 1 optional fields are as follows:

.. list-table:: Custom Scheduling Fields
   :widths: 20 10 10 10 15 10 15 10
   :header-rows: 1

   * - Field Name
     - Seconds
     - Minutes
     - Hours
     - Day-of-month
     - Month
     - Day-of-week
     - Year (Optional)
   * - **Allowed Values**
     - 0-59
     - 0-59
     - 0-23
     - 1-31
     - 1-12 or JAN-DEC
     - 1-7 or SUN-SAT
     - 1970-2099
   * - **Allowed Special Characters**
     - ``, - * /``
     - ``, - * /``
     - ``, - * /``
     - ``, - * ? / L W C``
     - ``, - * /``
     - ``, - * ? / L C #``
     - ``, - * /``

Special Characters
~~~~~~~~~~~~~~~~~~

* **\*** : Used to specify all values. For example, "*" in the minute field means "every minute".
* **?** : Allowed for the day-of-month and day-of-week fields. It specifies 'no specific value'. Use this when you need to specify something in one of the two fields, but not the other.
* **-** : Used to specify ranges. For example "10-12" in the hour field means "the hours 10, 11 and 12".
* **,** : Used to specify additional values. For example "MON,WED,FRI" in the day-of-week field means "the days Monday, Wednesday, and Friday".
* **/** : Used to specify increments. For example "0/15" in the seconds field means "the seconds 0, 15, 30, and 45". And "5/15" in the seconds field means "the seconds 5, 20, 35, and 50". Specifying '*' before the '/' is equivalent to starting at 0.
  *Note: "7/6" in the month field only turns on month "7", it does NOT mean every 6th month.*
* **L** : Allowed for the day-of-month and day-of-week fields. Short-hand for "last".
    * In day-of-month: "the last day of the month" (day 31 for Jan, 28 for Feb non-leap).
    * In day-of-week: "7" or "SAT".
    * In day-of-week after another value: "the last xxx day of the month" - e.g., "6L" means "the last Friday of the month".
    * *Warning: Do not specify lists or ranges when using 'L'.*
* **W** : Allowed for the day-of-month field. Specifies the weekday (Monday-Friday) nearest the given day. E.g., "15W" means "the nearest weekday to the 15th of the month".
    * If the 15th is Saturday, it fires on Friday the 14th.
    * If the 15th is Sunday, it fires on Monday the 16th.
    * It will not 'jump' over month boundaries (e.g., "1W" where the 1st is Saturday will fire on Monday the 3rd).
    * *Note: 'W' can only be used when the day-of-month is a single day.*
* **LW** : "Last weekday of the month".
* **#** : Allowed for the day-of-week field. Specifies "the nth" XXX day of the month.
    * "6#3" = the third Friday of the month (Day 6 = Friday, #3 = 3rd occurrence).
    * "2#1" = the first Monday.
    * "4#5" = the fifth Wednesday.
* **C** : Allowed for the day-of-month and day-of-week fields. Short-hand for "calendar". Values are calculated against the associated calendar. If no calendar is associated, it includes all days.
    * "5C" in day-of-month = "the first day included by the calendar on or after the 5th".
    * "1C" in day-of-week = "the first day included by the calendar on or after Sunday".

.. note::
   The legal characters and the names of months and days of the week are not case sensitive.

Examples
~~~~~~~~

* ``0 0 12 * * ?`` : Fire at 12pm (noon) every day
* ``0 15 10 ? * *`` : Fire at 10:15am every day
* ``0 15 10 * * ?`` : Fire at 10:15am every day
* ``0 15 10 * * ? *`` : Fire at 10:15am every day
* ``0 15 10 * * ? 2005`` : Fire at 10:15am every day during the year 2005
* ``0 * 14 * * ?`` : Fire every minute starting at 2pm and ending at 2:59pm, every day
* ``0 0/5 14 * * ?`` : Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day
* ``0 0/5 14,18 * * ?`` : Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day
* ``0 0-5 14 * * ?`` : Fire every minute starting at 2pm and ending at 2:05pm, every day
* ``0 10,44 14 ? 3 WED`` : Fire at 2:10pm and at 2:44pm every Wednesday in the month of March.
* ``0 15 10 ? * MON-FRI`` : Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday
* ``0 15 10 15 * ?`` : Fire at 10:15am on the 15th day of every month
* ``0 15 10 L * ?`` : Fire at 10:15am on the last day of every month
* ``0 15 10 ? * 6L`` : Fire at 10:15am on the last Friday of every month
* ``0 15 10 ? * 6L 2002-2005`` : Fire at 10:15am on every last Friday of every month during the years 2002, 2003, 2004 and 2005
* ``0 15 10 ? * 6#3`` : Fire at 10:15am on the third Friday of every month
* ``0 0 11 1-31/2 * ?`` : Fire on odd days at 11.00
* ``0 0 11 2-31/2 * ?`` : Fire on even days at 11.00

.. warning::
   Pay attention to the effects of **?** and **\*** in the day-of-week and day-of-month fields!