A Business Interval, also called a "Business Calendar", defines the periods of time that a job may (or may not) run. Unlike ordinary calendars, Business Intervals are not required to be oriented to calendar days and may even have millisecond resolution. Picture the calendar as a timeline running from left to right – Business Intervals define the ranges of time on this timeline that are either included or excluded. Included ranges of time define when jobs may run, and excluded ranges of time define the periods that the jobs may not run.
The "timeline" concept of business intervals means that they do not need to be confined to 24-hour periods – a business interval can include or exclude any range in the timeline even if it crosses from one calendar day to the next.
Business Intervals can be applied to Timer Triggers and Delay Triggers to help them calculate their future firing times. Intervals can also be applied in some specialized situations (for example, to help calculate timeouts for actions or triggers, or to specify an allowable time window for a File Exist Trigger to monitor for files).
For a complete working example of a business interval that is used with a Timer Trigger, refer to the /examples/end_users/business_calendar directory under your Flux installation directory.
Creating Business Intervals in the Desktop Designer
First, select "File" -> "New" from the Designer menu. Now choose "New Business Interval" from the list of available options and click "OK".
You'll be prompted to give your new interval a name. Just like workflows, you can also assign a namespace to your interval. Once you've entered a name for your new interval, click the "OK" button to proceed. This will display the editor window, which you can use to design and edit your business interval.
Notice the "Current includes / excludes" list on the right-hand side of the editor. You'll see that this list is empty, meaning that you have not defined any includes or excludes. By default, if there are no includes or excludes defined, then all ranges of time on the calendar are automatically excluded.
To help you easily keep track of what time intervals are included or excluded in your interval, the editor has a calendar display in the bottom-left of the window. This display provides a graphical representation of the time ranges that are (or are not) included in your interval. Dates and times highlighted in red are excluded periods, while dates and times in white are included periods. By default, all time ranges are excluded so your calendar will look something like:
As you begin to add includes and excludes, this display will be automatically adjusted to correspond with your changes.
To add a new include, click the green "+" icon next to the "Current includes/excludes" window. This will highlight the include/exclude editor where you will see several options available.
- Name: The name of your include or exclude. This allows you to provide descriptive names to track and organize your included and excluded intervals.
- Type: Intervals can have one of two types, "include" or "exclude". As mentioned above, an "include" interval specifies times that a job is allowed to run, while an "exclude" interval specifies times that a job is not allowed to run.
- Time: An include or exclude can have one of three types of time ranges – "All", "Day", or "Period".
- All: Indicates that the include or exclude should cover all possible time ranges.
- Day: Indicates that the include or exclude should cover an entire calendar day. There are two options for the "Day" include or exclude:
- Date: The first included or excluded calendar day. Note that regardless of the exact time that is set on the "Date" for this include / exclude type, the interval will cover the entire calendar day.
- Repeat time expression: A time expression applied to determine future dates to be included / excluded. For example, if the "Date" was set to 17 Nov 2010, and the "Repeat time expression" to +2d (every 2 days), then the include or exclude would also cover 19 Nov 2010, 21 Nov 2010, and so on.
- Period: Indicates that the include or exclude will cover a portion or period of time that may be larger or smaller than a single calendar day (like "08:00 to 12:00 Monday through Friday", or "23:00 to 01:00 daily"). There are 7 possible options that can be set for a "Period" include or exclude:
- Start date: The (optional) date and time that the include or exclude will begin. If this is set, the include or exclude will not begin until this date and time. This option cannot be set if the "Start time expression" or "Stop time expression" is set. If the "Start date" and "Start time expression" are both empty, the start date will automatically be set to the current date and time.
- Stop date: The (optional) date and time the include or exclude will end. If this is set, the include or exclude will not contain any period of time beyond this date and time. This option cannot be set if the "Start time expression" or "Stop time expression" is set.
- Start time expression: A ?Time Expression that specifies when the include or exclude will begin (for example, a "Start time expression" of 0 0 0 8 * * mon would indicate that the include or exclude begins next Monday at 08:00). This option cannot be set if the "Start date" or "Stop date" is set. If the "Start date" and "Start time expression" are both empty, the start date will automatically be set to the current date and time.
- Stop time expression: A ?Time Expression that specifies when the include or exclude will end (for example, a "Start time expression" of 0 0 0 8 * * fri would indicate that the include or exclude ends next Friday at 08:00). If this is set, the include or exclude will not contain any period of time beyond the calculated date and time. This option cannot be set if the "Start date" or "Stop date" is set.
- Duration time expression: A Time Expression that specifies the duration of the period to be included or excluded. For example, the relative time expression +8H would indicate that the period would last 8 hours, while the Cron-style time expression 0 0 0 8-17 would indicate that the period would last from 08:00 to 17:00 for each covered period. Used in conjunction with the "Repeat time expression" as described below.
- Repeat time expression: A Time Expression that specifies how frequently the include or exclude will occur. For example, the relative time expression +2d would indicate that the include or exclude period will occur every 2 days, while the Cron-style time expression 0 0 0 8 * * mon-fri would indicate the the include or exclude would occur at 08:00 on Monday through Friday. This is used in conjunction with the "Duration time expression". When the include or exclude reaches is start date, it first applies the "Duration time expression" to calculate the included or excluded period (if any) that occurs beginning at that time. Next, it applies the "Repeat time expression" to the start date to calculate the start of the next period, where it again applies the "Duration time expression". This is repeated (applying the repeat time expression each time to the last value calculated) until the include or exclude reaches its "Stop date" or "Stop time expression", or indefinitely if neither of those values is set.
- Count: The (optional) value that specifies how many times the period should be evaluated. A count of 5, for example, would indicate that only the first 5 periods calculated should be used for the include or exclude. Can be used as an alternative to the "Stop date" or "Stop time expression.
One typical example of a business interval is a calendar that only allows jobs to run during typical working hours. For example, you may want to define a calendar that only allows jobs to run from 08:45 to 16:30 daily, Monday through Friday. To do so, you could just create a "Period" include with a duration time expression of +7H+45m and a repeat time expression of 0 0 45 8 * * mon-fri. This include says "include a period of time starting at 08:45 every Monday through Friday and lasting a duration of 7 hours and 45 minutes".
Managing Includes and Excludes
Once you've created a few includes and includes, you will see them appear in the "Current includes/excludes" list on the right-hand side of the editor.
To determine the final interval, Flux applies each of these includes and excludes in descending order starting at the top of the list. For example, consider the case where you have one include covering the "All" time period, and one exclude for the "Day" time period on 17 Nov 2010.
If the "All" include is listed above the "Day" exclude, then Flux apply them in this order:
- Include all days
- Exclude 17 Nov 2010
Which means that the exclude will be successfully applied. But consider the opposite case, where the exclude is listed above the include. In this instance Flux would apply them in this order:
- Exclude 17 Nov 2010
- Include all days
Now the include would wipe out the exclude because it was applied afterward! It is important to consider the ordering of includes and excludes when creating your interval.
You can use the arrow buttons to the right of the include/exclude list to reorder the includes and excludes as appropriate.
Note that when using Time Expressions within your Business Interval to define included and excluded time periods, you cannot use the five special symbols b, D, e, h, or n.
Finally, when using Business Intervals with Relative Time Expressions, the Relative Time Expression treats a day as a holiday only when the Business Interval excludes that entire calendar day, from midnight to midnight. If a day is partially excluded only, it is not considered a holiday.
Using Business Intervals with Timer Triggers (or other Time Expressions)
If you have a Timer Trigger (or any other time expression) where you would like to apply your business interval, you will need to include some special characters in your time expression. These characters are:
In a Cron-style time expression, the "b" character indicates all values for the given column that are included in the business interval, while the "h" character indicates all values that are excluded.
For example, the Cron-style expression 0 0 0 *b indicates "fire at the top of the hour for every hour value included in the interval". If the business interval included the time from 08:00 to 17:00, then this time expression would cause the trigger to fire at 08:00, 09:00, and so on, until 17:00 (the last included value). Similarly, a Cron-style expression of 0 0 0 *h for the same interval would cause the trigger to fire at 18:00, 19:00, and so on until 07:00 (the last excluded hour).
In a relative time expression, the characters "b" and "h" refer to included and excludes days, respectively. In a relative time expression, a day is only considered "excluded" if the entire calendar day is excluded in the interval – this means that even if just one hour of the day is included, it will not be recognized as an excluded day when using the "h" character.
For example, the relative time expression +b (8H)0m (0s)0S means "fire at 08:00 on every day that is included in the business interval". If the business interval includes Monday through Friday but excludes the weekends, then this relative time expression would fire Monday through Friday at 08:00 but ignore Saturday and Sunday. Similarly, the expression +b (8H)0m (0s)0S means "fire at 08:00 on every day that is excluded from the business interval", so this relative time expression (for the same interval) would only fire on Saturday and Sunday.
These special characters are discussed in greater detail in ?Time Expressions.
You will also need to indicate which business interval the action or trigger should use. For a Timer Trigger, you'll just need to set the "Business Interval" property to match the interval you would like to use.
A real world business interval example from our Technical Support department
Question: How do I schedule a job to fire at 6 am from the 1st day of the month to the 6th-to-last day, then every 4 hours on the last 5 days of the month?
Answer: This schedule can be modeled by using a business interval with two Cron-style repeat time expression includes.
The first include, which will schedule the job to fire at 6 am from the 1st day of the month to the 6th-to-last day, will have a repeat time expression like this:
The "6" in the hours column indicates that this schedule will fire at 06:00, or 6 am. The "(1; $<5; *)" in the days-of-month column indicates that this schedule will start on the first day of the month, and fire as long as there are more than 5 days remaining in the month.
The second include, which will schedule the job to fire every 4 hours on the last 5 days of the month, will have a repeat time expression that looks like this:
The "*/4" in the hours column indicates that this schedule will fire every four hours. The "$<4,$<3,$<2,$<1,$" in the days-of-month specifies that the schedule should fire on the fourth-to-last day of the month, the third-to-last, and so on until the end of the month.
Both includes will also need a duration time expression. In this case, we will give the business interval a duration of 5 minutes, which will give the timer trigger enough of a window to ensure that it fires. Therefore the duration interval should be set to:
You can leave the "Start date" and "Stop date" fields empty.
Once the interval is created, you only need to set a time expression on your Timer Trigger that will fire at the top of every included hour. This time expression will look like:
That's it! Your trigger is now configured to use the custom business interval.
Business Interval Performance
Due to the complexity and open-ended nature of some business intervals, they can be slow to load when exporting workflows that use business intervals for their scheduling.
If your business intervals are not performing to the desired level, try to design your time expressions to include only the particular time and date ranges that you require, and limit unnecessary field. Consider using '0' rather than '*' for fields like milliseconds, seconds, and minutes where your expression does not need to fire more than once, and limit date ranges where possible (a timer trigger with the "years" column set to "2012-2017", for instance, will be processed more quickly than one with an open-ended date range).
This time expression design will help avoid some of the congestion that can occur when Flux needs to process a business interval over a very large date range on a trigger, and ensures that the engine can process your workflows much more quickly.