Child pages
  • Time Expressions

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Clarified the grammar a bit and spelled out abbreviations.

...

In order (from left to right), each column represents the following corresponding constraint:

milliseconds

seconds

minutes

hours

days-of-month

months

days-of-week

day-of-year

week-of-month

week-of-year

year

If a column is unconstrained (using the '*' character) then it will fire at every possible instant represented by the column. A completely unconstrained Cron-style expression, therefore, would fire at every millisecond continuously, so naturally it is not practical to use a Cron-style expression without applying some constraints.

Each column has its own range and type of accepted values. The table below shows the valid range for each column:

Column

Values

Milliseconds

0-999

Seconds

0-59

Minutes

0-59

Hours

0-23

Days-of-month

1-31 or <position><weekday of month> (see Special Values for the Days of Month and Day of Year Columns below for more information).

Months

0-11 or jan-dec

Days-of-week

1-7 or sun-sat

Day-of-year

1-366 or <position><weekday of year> (see Special Values for the Days of Month and Day of Year Columns below for more information).

Week-of-month

minimum-6, where minimum is either 0 or 1 (depending on your locale). In the United Sates, the minimum value is 1.

Week-of-year

minimum-53, where minimum is either 0 or 1 (depending on your locale). In the United Sates, the minimum value is 1.

Year

1970-3000

For a practical example, consider a workflow that needs to run at 12:00 (noon) every weekday. In this case, the Cron-style time expression must be constrained, to provide some limitation on when the expression can fire.

...

These special values have the syntax <position><weekday abbreviation>. The possible position values are:

Value or Range

Meaning

1-6 (days of month) or 1-53 (day of year)

Run on the specific number value for the given weekday (see table below). For example, setting "1MO" in the days of month column will include the first Monday of the month. Likewise, "44FR" in the day of year column will include the 44th Friday of the year.

^

Run on the first possible instance of the given weekday. For example, "^TU" in the days of month column will include the first Tuesday of the month. Similarly, "^WE" in the day of year column will include the first Wednesday of the year.

$

Run on the last possible instance of the given weekday. For example, "$TH" in the days of month column will include the last Thursday of the month. Similarly, "$SA" in the day of year column will include the last Saturday of the year.

The possible weekday abbreviations values are:

Abbreviation

Day of Week

SU

Sunday

MO

Monday

TU

Tuesday

WE

Wednesday

TH

Thursday

FR

Friday

SA

Saturday

Note that these abbreviations are different than those used for the days of week column. Take care to ensure that you are using the appropriate abbreviations in each column.

...

To help with this, Cron-style time expressions accept two special symbols:

Symbol

Explanation

b

A business unit of time – that is, a unit that is included in the business interval.

h

A non-business unit of time – that is, a unit that excluded from the business interval.

Using one of these special characters in a column of the Cron-style time expression indicates to Flux, "use only the values in this column that are included (or excluded) from the business interval).

These special characters must be preceded by an identifier, to describe how the character should be applied (i.e., "the first unit of time for this column if it is allowed", "the 5th unit of time if it is not allowed"). The identifiers that can be used are:

Value

Affect

*

Include all business units of time (using the 'b' character) or non-business units of time (using the 'h' character) for this column. For example, setting "*b" in the days of month column will include all days of the month that are included in the business interval. Likewise, "*h" in the days of month column will include only days of the month that are excluded from the interval.

Numeric value n (where n is 1, 2, 3, etc.)

Include the nth business unit of time (using the 'b' character) or non-business until (using the 'h' character). For example, setting "2b" in the days of month column would include the second business day of the month. Likewise, setting "3h" in the days of month column would include the 3rd non-business day of the month.

^

Include the first business (or non-business) unit of time for this column. A value of "^b" in the days of week column would include the first day of the week allowed by the business interval. Similarly, "^h" in the days of week column would include the first day of week not allowed by the business interval.

$

Include the last business (or non-business) unit of time for this column. A value of "$b" in the days of week column would include the last day of the week allowed by the interval, and a value of "$h" would include the last day of the week not allowed.

These can be combined with other concepts for Cron-style time expressions, including:

...

The great part about the Cron for-loop is that you can condense multiple tasks into just a single Cron expression. There is no need for three Cron-expressions, three TimerTriggers, and three tasks. Just one of each will do.

Here is another example, in . In this case, we're scheduling a service task to execute every 15 mins minutes from 20:15 to 23:15 on Mon-Fri, Monday to Friday

Panel

(0 0 15,30,45 20-22 * * MON-FRI | 0 0 0 21-23 * * MON-FRI | 0 0 15 21-23 * * MON-FRI)

...

Relative time expressions consist of the following syntax. They may be combined to form more complex time expressions.
Relative time expression Syntax| + <number> <unit> | Move forward in time by number years, months, weeks, days, hours, minutes, seconds, or milliseconds. If number is omitted, it defaults to 1. |

- <number> <unit>

Move backward in time by number years, months, weeks, days, hours, minutes, seconds, or milliseconds. If number is omitted, it defaults to 1.

> <number> <unit>

Move forward in time by number absolute days-of-the-week, absolute months, holidays, non-holidays, weekdays, weekend days, or business days. If number is omitted, it defaults to 1. If date is already on the given day-of-week or month, then number is first decremented by 1.

< <number> <unit>

Move backward in time by number absolute days-of-the-week, absolute months, holidays, non-holidays, weekdays, weekend days, or business days. If number is omitted, it defaults to 1. If date is already on the given day-of-week or month, then number is first decremented by 1.

^ <unit>

Go to the beginning of the current year, month, week, day, hour, minute, second, or millisecond. Going to the beginning of one time unit (such as hour) also causes any sub-units (such as minute, second, and millisecond) to go to the beginning.

$ <unit>

Go to the end of the current year, month, week, day, hour, minute, second, or millisecond. Going to the end of one time unit (such as hour) also causes any sub-units (such as minute, second, and millisecond) to go to the end.

@ <n> <unit>

Go to the nth year, month, day-of-month, hour, minute, second, or millisecond. Recognized units are y, M, d, H, m, s, and S.

@ <n> <day>

Go to the nth day-of-week in the current month. n is 1-based. If n is omitted, go to the first day-of-week in the current month. Recognized day-of-week values are sun, mon, tue, wed, thu, fri, and sat.

@ ! <day>

Go to the last day-of-week in the current month.

? <unit>{<then-time-expression>} {<else-time-expression>}

If the current time occurs on the given unit (day-of-week, month-of-year, business day, etc), apply the then-time-expression. Otherwise, apply the optional else-time-expression. These conditional time expressions may be nested.

The following units are recognized.
Recognized Units| Unit | Description |

y

Year

M

Month

w

Week

d

Day

H

Hour

m

Minute

s

Second

S

Millisecond


h

Holiday

n

Non-holiday

D

Weekday: Monday through Friday

e

Weekend day: Saturday through Sunday

b

Business day: A day specified using a business interval to define an acceptable business day. For instance, a day that is not a weekend or holiday.



mon

Monday

tue

Tuesday

wed

Wednesday

thu

Thursday

fri

Friday

sat

Saturday

sun

Sunday


jan

January

feb

February

mar

March

apr

April

may

May

jun

June

jul

July

aug

August

sep

September

oct

October

nov

November

dec

December

More Examples

Relative time expression Examples| +30d-8H | Move forward 30 days, then backup 8 hours. |

-12H+30s

Move backward 12 hours, then forward 30 seconds.

+23y-23M+23S-8m

Move forward 23 years, then backup 23 months, then move forward 23 milliseconds, then backup 8 minutes.

>sat

Move forward to Saturday.

>3sat>nov

Move forward 3 Saturdays, then skip ahead to November.

<5may>fri

Move backward 5 Mays, then advance to Friday.

@2005y+2y<sun

Go to the year 2005, then move forward 2 years, then backup to Sunday.

(2M)22d (8H)30m

Go to March 22nd, 8:30 AM of the current year.

^M>4mon

Go to the beginning of the month, then advance 4 Mondays.

+M^M>4mon

Go to the beginning of next month, then advance 4 Mondays.

^d+7H

Go to the beginning of today, then advance 7 hours.

>3D

Move forward three weekdays.

<4e

Move backward 4 weekend days.

>n

Move forward to the next non-holiday.

?D{+d}

If today is a weekday, advance a day.

?b{}{+2d}

If today is not a business day, advance two days.

Designing and Testing Time Expressions

...