Introduction
JobScheduler Calendars can be configured to meet a wide range of business requirements. This first part of this article describes how to configure a single Calendar to describe a basic five-day business week with holidays. The second part of the article describes how within this Calendar an Order can be configured to be executed on every third business day.
This approach can be contrasted with the approach described in the Calendar Use Cases - Managing Working Day and Non-Working Day Calendars article in which separate Working Day and Non-Working day Calendars are used to configure a "normal" Monday to Friday business week and holiday plan respectively.
Article Scope
This article describes how to configure basic Calendars with the intention that users will be able to adapt the procedures described to meet a large part of their everyday needs. This article is not intended to provide a description of all the possible configuration items. The JOC Cockpit - Calendar Management article provides starting point for more general information about the JOC Cockpit's Calendar feature.
Feature Availability
The Calendar feature is introduced with JobScheduler FEATURE AVAILABILITY STARTING FROM RELEASE 1.12 .
Calendar Configuration and Order Assignment
Permissions
Note that the creation of Calendars requires that a user is signed in with an account that has been granted the necessary permissions. See your system administrator if you are not able to follow the examples shown.
Calendar Configuration
Calendars are created in the JOC Cockpit Resources / Calendars view by clicking the Add Calendar button as shown in the first screenshot.
This will open the Create Calendar modal window as shown in the next screenshot:
Note that additional fields (Option for Reason, Select Reason, etc.) that are not shown in the screenshot may be shown at the start of the Create Calendar window. The information for these fields is for the Audit Log and settings in the user's account determine whether or not these fields are shown and are mandatory. See the Reasons setting section of the Audit Log article for more information.
The Name, Type, and Valid To fields are mandatory: the Category, Path and Valid From fields are not.
The Path field allows to store the Calendar in a folder structure. Use a slash "/" to separate sub-folders.
If a Valid From date is not set then the current date will be used.
Performance may be slowed if the Valid To setting is too far in the future.
Configure a Monday to Friday Working Week
The working days are configured by specifying a number of Frequencies for the Calendar. Frequencies are rule sets for weekdays, month days, recurring days etc.
The Add Frequency button will become active once the information described in the previous section has been entered. Leave the Included Frequencies tab active.
Click on the Add Frequencies button and in the the Weekdays Tab, which is the default tab, fill out the Weekdays section as shown in the next screenshot.
Clicking on the Add Frequency button as shown above will cause the days selected to be noted as shown in the next screenshot.
Note that the configuration information has not yet been saved.
View the configured Frequency
Click on the Calendar icon under the Action header. This will open a preview of the Calendar.
Now click on the Close button to close the preview and then click on Close in the Add Frequencies modal to return to the Create Calendar window which will display the list of Included Frequencies as shown.
Exclude National Holidays from the List of Working Days
Now click on the Excluded Frequencies tab to add days for which jobs should not be executed on and then click on the Add Frequency button.
In the Add Frequencies window now select the National Holidays tab and then a country - in this example we will use the USA. This will cause a list of national holidays to be displayed. Set the Year field to the correct value (in this case the default 2017 is correct) and then select the days to be observed. The window should now appear as shown in the following screenshot:
Then click on Add Frequency to note the Frequency (which has not yet been saved). The Window will now appear as shown in the next screenshot:
As our Included Frequencies are valid to 2018, holidays should also be added for that year.
To do this change the Year to 2018, click Select all and then click on Add Frequency again.
Now click on Close to return to the Create Calendar window:
The list of excluded working days will now appear as shown in the above screenshot. Note that none of the Frequencies added has yet been permanently saved.
Clicking once again in the Calendar icon below the Action header will reopen the Calendar Preview window for an individual frequency. However, selecting the All Frequencies in the Select box at the top right of the window and the year 2018 will, for example, show the correct listing for all frequencies as can be seen in the next screenshot:
Note that days selected in the Non-Working Days tab are marked as active (orange background) and that days that were unspecified (Saturdays and Sundays) are left white.
Now click on the Close button to return to the Add Frequencies window and then Close again to return to the Create Calendar window.
Then use the Submit button to permanently save the configuration and return to the Resources / Calendar view as shown in the next screenshot.
This Calendar is now ready to be used for an Order or Job.
Assigning a Calendar to an Order
Go to the Job Chains view and select an Order. The Job Chain and Order to be used for this article are shown in the screenshot below. Now open the Additional Options (ellipsis) menu and select Set Run-time:
This will open the Set Run-time modal window for the Order as shown:
Use the Assign Working Day Calendar button to open the Calendar selection window.
Select the calendar and then click on the Apply button - not shown in the screenshot - to return to the Set Run-time modal window which will now appear as shown below:
The next screenshot shows how the Edit XML button in the Set Run-time window can be used to inspect and, if required, edit individual entries in the Calendar configuration:
It is probably a good idea at this stage to save the assignment by clicking on Submit which will also close the Set Run-time window. Reopen the window using the Set Run-time menu item as described at the start of this section.
Configuring the Order Periods (Run-Times)
Periods are used to specify the time or times at which a Job or Order will run on the days that have been specified in the Calendar. In addition, the behavior when the "regular" execution date of a Job or Order falls on a non-working day such as a holiday is specified as part of the Period.
Configuration of a new Period is started by clicking on the + symbol alongside the relevant Calendar as shown in the screenshot above. This will open the Create Period modal window.
Enter a Start Time - here a Single Start at 15:00 has been entered. Clicking the Save button now will cause the Period configuration to be added to the Order.
Note that the On Non-Working Day setting - will not function with the calendar configured in the first half of this article. On Non-Working Day only becomes effective when a Non-Working Day calendar is used. Such a configuration is described in the Calendar Use Cases - Managing Working Day and Non-Working Day Calendars article.
The next screenshot shows that two Single Start Periods have been configured - at 15:00 and at 21:00.
Note again that the changes made to the configuration will only be saved when the Submit button is clicked.
Clicking the Submit button will close the Set Run-time modal window and return to the Job Chains view.
A short time after this is carried out the Next Start time for the Order should change from 00:00:00 to the correct value - in this case 19.12.2017 15:00 as shown in the screenshot below.
Inspecting the Configuration
The Show Assigned Calendars menu (ellipsis symbol shown in the previous screenshot) can be used to show which calendars have been assigned to an Order as shown in the next screenshot:
The Show Calendar item in the same menu can be used to show either Monthly or Yearly views of the calendars.
Individual Period starts are shown in the Monthly views (first screenshot below) and unspecified and excluded days are highlighted in the Yearly view (second screenshot below).
Restricting Job and Order Starts
The situation where Jobs and Orders are not to run on every working day can be readily configured in a number of ways.
This section describes how to extend the configuration so that the Order only runs on every 3rd working day.
Note that in the current calendar configuration (described in the first part of this article), Working Days were defined as being Monday to Friday, less the excluded National Holidays. Non-working days were not specifically defined. This means that every 3rd Working Day will be quite rigidly interpreted and that more complex handling of non-working days (such as execution on the preceding or succeeding day) is not possible. A more flexible configuration using separate Working Day and Non-Working Day Calendars is described in the Calendar Use Cases - Managing Working Day and Non-Working Day Calendars article.
Configuration Procedure
Re-open the Set Run-time modal window for the Order as shown below:
Click on the "+" symbol in the Restrictions column to add a new restriction for the Calendar as shown in the next screenshot:
This will open the Add Frequencies modal window. Now select the Recurring Days tab, complete the fields as shown in the next screenshot and click Add Frequency to note the configuration.
The Valid From setting is particularly important as it defines the starting point for the calculation of the recurring days.
Now repeat this procedure for 2018: change the Valid From and Valid To settings to the 1st January 2018 and 31st December 2018 respectively and then click on Add Frequency again.
In the screenshot shown below it can be seen that two Every 3rd day frequencies have been set - one for December and one for the whole of 2018.
Now click Close and the Every 3rd Day Restriction will be added to the Set Run-time configuration as shown below:
The Every 3rd Day Restriction effectively functions as a filter on the wkg_day_mo-fr-hol Calendar. It means that the Order will run on every 3rd day that has been defined as a Working Day and that all other days will be ignored.
As already noted above, in this article, holidays have been specified in this Calendar as excluded Working Days. This effectively effectively excludes a more sophisticated behavior around non-working days such as holidays, such as execution on the preceding day. See the Calendar Use Cases - Managing Working Day and Non-Working Day Calendars article for an alternative approach that allows execution to be moved.
Checking the Configuration
The configuration can be checked in two ways:
- With the Edit XML function in the Set Run-time modal window:
- With the Calendar View window, which is accessed using the Order's Show Daily Plan function:
The Valid From 1st Dec 2017 setting in the 2017 Every 3rd day Restriction filters out all dates from the current month (November) but provides a clear starting point for calculating execution dates in December. Similarly the Valid From 1st Jan 2018 setting in the 2018 Every 3rd day Restriction filters provides a clear starting point for calculations for that year. This also means that in the changeover from the 2017 restriction to the 2018 only one working day will be left between execution on the 28th of December and on the 2nd of January.
Note that as the 1st of January is not a Working Day, the Order will be first executed on the 2nd. Execution proceeds regularly until the 15th of January, which is a Non-Working Day (Martin Luther King day) and therefore ignored, with the next execution taking place on the 16th.
Comparison with Behavior defined using Multiple Calendars
The approach described in this article has the advantage of a single Calendar being used to define the days on which Job and Order execution will occur. This approach allows regular execution of Jobs and Orders - i.e execution every business day or every x-th business day - to be suppressed. This approach does not allow more sophisticated behavior such as execution on the preceding day to be implemented around non-business days such as holidays. See the Calendar Use Cases - Managing Working Day and Non-Working Day Calendars article for an alternative approach that allows execution to be moved around non-business days.