| Table of Contents |
|---|
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 a basic Working Day Calendar. It 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
...
| Display feature availability | ||
|---|---|---|
|
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 that should be filled out 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 Useruser'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 End Date Valid To fields are mandatory. The : the Category, Path and Valid From Start Date fields fields are not mandatory.
The Path is used to ... field allows to store the Calendar in a folder structure. Use a slash "/" to separate sub-folders.
If a Valid From Start Date 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 above information described in the previous section has been entered.
Leave the Included Frequencies tab active.Frequencies are sets of ... description / definition
Click on the Add Frequencies button and in the then select the Weekdays Tab Frequency Type, which is the default tab, .
Now 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 no 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 deactivate the current date field - in this case the 24th November - by clicking on it once. This will cause the field background to be colored orange.Now click on the Close button to close the preview . and then click on close 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 on for which it will jobs should not be worked executed on and then click on the Add Frequency button.
In the Add Frequencies window now select the National Holidays tab Frequency Type and then a country - in this example we will use the USA. This will cause a list of official national holidays to be displayed. Select All and then enter the current year Set the Year field to the correct value (in this case the default 2017 is correct) in the Year field. Click on Add Frequency. This will result in the following screenshot: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 permanently saved). The Window will now appear as shown in the next screenshot:
As our Included Frequencies were up 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 .Selecting for an individual frequency. However, selecting the All Frequencies in the Select box at the top right of the window and the Year year 2018 will, for example, show the followingthe correct listing for all frequencies as can be seen in the next screenshot:
Note that days selected in the Holiday 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:
Open This will open the Set Run-time modal window for the Order as shown.:
Use the Assign Working Days CalendarDay 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 Period function is used to configure the time or times at which the job 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 and is started by clicking on the + symbol alongside the relevant calendarCalendar 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 2419.1112.2017 2115:00 as shown in the screenshot below.
Inspecting the Configuration
The Show Assigned Calendars The Additional Operations menu (ellipsis symbol shown in the previous screenshot) can be used to show which calendar(s) has or calendars have been Assigned assigned to the an Order as shown in the next screenshot:
Comment ....
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 as (second screenshot below).
Note that the screenshots were made on the 19th December 2017 and that dates before this are not shown.
Restricting Job and Order Starts
The situation where Jobs and Orders are not to run on every business - i.e. working - day can also be readily incorporated in this Calendarconfigured in a number of ways.
This section of the article describes how to extend the configuration so that the Order only runs on every 3rd working day, taking account of holidays and weekends..
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 Wkg Day - Mo-Fr Calender using the Edit Calendar menu item Set Run-time modal window for the Order as shown below.:
Select the Edit Frequency function (pencil icon) in the Update Calendar window as shown:
Now, in the Update Frequencies window select the Recurring Days tab and complete the fields as shown:
Click Add Frequency and the Frequency entry will be modified as shown in the screenshot above.
Now click on Close to return to the Set Run-time window.
The final configuration, if required, is to edit the Periods and specify the behavior On Holiday.
The default Suppress Execution setting can be seen in the following screenshot
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 Frequency Type, complete the fields as shown in the next screenshot and click Add Frequency to note the configuration.
The Valid From setting is particularly important with the Recurring Days Frequency Type 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 daysCalculation starts with the 1st of January, which, with the 15th is a non-working day in the USA. Here the wrong values are calculated ....