Period Functions
Sometimes complex calculations are required to determine when a Time Window should be open. For such situations, you can use Period Functions.
Period Functions (Configure > Automate > Calendar Tools > Period Functions) are RedwoodScript functions that evaluate to true or false to determine whether the associated Time Window should be open or closed.
When you import SAP Calendars (such as the Factory and Holiday calendars), these become available as Period Functions. You can also define your own Period Functions.
The following Period Functions are built into RunMyJobs.
| Period Function | Description |
|---|---|
| SAP_FactoryCalendar | Uses the Factory calendar from an SAP instance to schedule SAP jobs. The calendaring data must be imported from the instance. |
| SAP_HolidayCalendar | Uses the Holiday calendar from an SAP instance to schedule SAP jobs. The calendaring data must be imported from the instance. |
| System_InDayRecurrence | Recurrence within a day. |
| System_Easter | Calculates Easter or Easter-based holidays. Accepts one dayNumber Parameter, which is the offset to Easter Sunday. No parameter or dayNumber=0 means Easter Sunday. |
| System_FiscalPeriods | Calculates open days based on periods in a fiscal year. |
Caching Objects in Period Functions
It is important to note that all Time Windows that use a given Period Function share the same instance of that Period Function, and that parameter values can be cached for performance reasons.
Do not cache SchedulerEntities, such as Time Windows, in Period Functions, because they may have a long lifetime, or the dispatcher may refresh the session, causing errors such as JCS-122017: Trying to use non-attached object TimeWindow.
SAP Calendars
SAP calendars are imported and converted to Period Functions to be used in Time Windows. Period functions of SAP calendars take arguments. The factory calendar, for example, can include several different calendars, which all must have a unique calendar ID.
SAP Calendar Period Functions accept the following arguments:
calendar=<SAP Instance> <Calendar ID>
| Parameter | Description |
|---|---|
<SAP Instance>
|
The SAP instance name. |
<Calendar ID>
|
The calendar ID. Usually two characters. This an be found in the output file of the SAP_ImportCalendar Job. |
You should only specify instances for which you have imported the calendar with the SAP_ImportCalendar Job Definition. Also, the specific calendar ID must exist in that SAP instance. Use the Opens at tab of the Time Window edit screen to make sure you are using the correct values.
Note: Period Function parameters are case-sensitive.
Fiscal Period Function
The Fiscal Period Function is used to calculate open days based on the fiscal year. Both US and ISO-8601 fiscal years are supported. Fiscal years divide quarters into one five-week period and two four-week periods.
US-style fiscal years start on January 1st. ISO-8601 fiscal years always start on Monday. The 4-5-4 fiscal period starts on the 2nd workday to the 6th workday of each period.
| Parameter | Description | Values | Default |
|---|---|---|---|
| week{1｜2｜3} | Specifies the number of weeks for the first, second and third period of the quarter | 4 (period is 4 weeks long) 5 (period is 5 weeks long) |
week1=4 week2=4 week3=5 |
| weekday{From｜To} | Specifies the day(s) of the week. | 1 (Sunday), 2 (Monday), 3 (Tuesday), 4 (Wednesday), 5 (Thursday), 6 (Friday), 7 (Saturday), 8 (Workday), 9 (Weekends), 10 (Workweek), 0 (Anyday) | weekdayFrom=8 (Workday) weekdayTo=8 (Workday) |
| weekOrDay{From｜To} | Specifies the number of the day in the period; if the number is larger than the number of days in the period, it specifies the last weekday. | integers >=1 (1, 2, 3 ...) |
weekOrDayFrom=1 (first day of the period) weekOrDayTo=1 (first day of the period) |
| weekStartsAtWeekday | Specifies the first day of a week (requires isoPeriod to be set to true) | 1 (Sunday), 2 (Monday), 3 (Tuesday), 4 (Wednesday), 5 (Thursday), 6 (Friday), 7 (Saturday) | weekStartsAtWeekday=2 |
| weekDayDefiningFirstWeek | Specifies the day to use to calculate first week of the year | 1 (Sunday), 2 (Monday), 3 (Tuesday), 4 (Wednesday), 5 (Thursday), 6 (Friday), 7 (Saturday) | weekDayDefiningFirstWeek=5 |
| isISOPeriod | Specifies the start of the year. | true (Monday) false (January 1st) | false (Year starts on January 1st). |
Using Fiscal Period Functions
When you create a Fiscal Period Function, begin by specifying the number weeks of your three periods (for example week1=4 week2=4 week3=5).
Next, specify an open time frame, which can be a day or a number of days using the weekdayFrom and weekdayTo parameters. For example, weekdayFrom=2 and weekdayTo=6 is equivalent to weekdayFrom=8 and weekdayTo=8; your work week is from Monday to Friday. The difference between weekdayFrom=8 and weekdayFrom=10 is that the latter is a week, not individual days. This is important when we start counting below.
Finally, specify when the time frame occurs in your 3 periods using the weekOrDayFrom and weekOrDayTo parameters. For example weekOrDayFrom=5 and weekOrDayTo=5 means the last work week of each period (because 5 is greater than 4).
If you want the Job to run only on the 5th week of a period -- that is, skip it on two of the three periods (those that are 4 weeks in length) -- you need to create a second Time Window which is open on the 4th week of a period. This Time Window must then be specified in the Disabled During Time Window field of the Time Window element where you specified the Period Function.
To illustrate the difference between weekdayFrom=8 and weekdayFrom=10, the following table lists equivalent combinations:
| Time frame in Workdays | Time frame in Workweeks |
|---|---|
weekdayFrom=8 weekdayTo=8 weekOrDayFrom=1 weekOrDayTo=5 |
weekdayFrom=10 weekdayTo=10 weekOrDayFrom=1 weekOrDayTo=1 |
weekdayFrom=8 weekdayTo=8 weekOrDayFrom=1 weekOrDayTo=10 |
weekdayFrom=10 weekdayTo=10 weekOrDayFrom=1 weekOrDayTo=2 |
If isISOPeriod is true, then the Monday of the first week of the year is calculated as follows:
- The week with the year's first Thursday in it.
- The week with 4 January in it.
You can customize this behavior with the following parameter:
weekDayDefiningFirstWeek
Recurrence Within a Day
This Period Function is used to create recurrences in a day.
| Parameter | Description | Values | Default |
|---|---|---|---|
startHour
|
The hour the recurrence starts | 0-23 | 0 |
startMinute
|
The minute the recurrence starts | 0-59 | 0 |
startSecond
|
The second the recurrence starts | 0-59 | 0 |
endHour
|
The hour the recurrence ends | 0-23 | 23 |
endMinute
|
The minute the recurrence ends | 0-59 | 59 |
endSecond
|
The second the recurrence ends | 0-59 | 59 |
intervalHour
|
The interval hour of the recurrence | 0-23 | 0 |
intervalMinute
|
The interval minute of the recurrence | 0-59 | 15 |
intervalSecond
|
The interval second of the recurrence | 0-59 | 0 |
durationHour
|
The duration of the opening (hours) | 0-23 | 0 |
durationMinute
|
The duration of the opening (minutes) | 0-59 | 1 |
durationSecond
|
The duration of the opening (seconds) | 0-59 | 0 |
startHour,startMinute, andstartSecondspecify the start of the recurrence in the day (default 0:00:00).endHour,endMinute, andendSecondspecify the end of the recurrence in the day (default 23:59:59).intervalHour,intervalMinute, andintervalSecondspecify interval at which the function should open (default is 0:15:00).durationHour,durationMinute, anddurationSecondspecify how long the recurrence period should be open (default is 0:01:00).
Note the following:
- if
duration >= interval, the Period Function is always open. endTime = 0is evaluated as the start of the following day.
If the duration >= interval, the Period Function is always open. If EndTime=0, the EndTime will be the start of the next day.
Deleting Period Functions
You can delete Period Functions only if no other objects have relationships to them. For example, if there are Time Windows that use a Period Function, the Period Function cannot be deleted until all Time Windows that use it have been edited to not use it anymore. You can see all objects that relate to a Period Function under Related Objects in the Detail View.
Security
The privileges available in the Security tab are as follows. For more information, see Security Tab.
| Privilege | Description |
|---|---|
| PeriodFunction.Create | Create Period Functions |
| PeriodFunction.Delete | Delete Period Functions |
| PeriodFunction.Edit | Edit Period Functions |
| PeriodFunction.View | Access Period Functions |
Example
In the following examples, tables illustrate the fields of the Time Window element that need to be filled, all other fields are left with their default values.
SAP Calendar Period Function Parameter
In this example, you want to have the time open on the fourth workday of the SAP Factory Calendar of every month. You need 3 Time Windows in this case. One that is always closed, one that uses the SAP Factory Calendar, and one for the day shift.
Note: We need the TW_AlwaysClosed and TW_GermanFactoryCalendar Time Windows below because we want to force Redwood Server to use the SAP Calendar for determining and counting workdays. This way it takes public holidays into account.
You need to create a Time Window that is always closed. Only the following fields need to be specified:
| Field | Value |
|---|---|
| Name | TW_AlwaysClosed |
| Is Calendar | true (checked) |
You also need a Time Window to use the SAP Factory Calendar:
| Field | Value |
|---|---|
| Name | TW_GermanFactoryCalendar |
| Is Calendar | true (checked) |
The German factory calendar of the PR1 instance is used in a Time Window element as follows:
| Field | Value |
|---|---|
| Period Function | SAP_FactoryCalendar |
| with parameters | calendar=PR1 FR |
The Time Window with the day shift is the one you will use in Redwood Server. In this case, it should be open on the first workday of the month and shift 3 days forward when the open day falls on a day where TW_AlwaysClosed is closed.
| Tab | Field | Value |
|---|---|---|
| Time Window | Name | SAP_4th_Workday |
| Time Window | Is Calendar | true (checked) |
| Time Window | If an open day is closed during | TW_AlwaysClosed |
| Time Window | the shift this day | Forward |
| Time Window | to the | 3 |
| Time Window | open day in | TW_GermanFactoryCalendar |
| Elements | and from the | 1st workday of the month |
Easter Period Function
The following Time Window element defines Good Friday (Friday preceding Easter).
| Field | Value |
|---|---|
| Period Function | System_Easter |
| with parameters | dayNumber=-2 |
Fiscal Period Function
If you want a Time Window to open on the third Monday of each period:
| Field | Value |
|---|---|
| Period Function | System_FiscalPeriods |
| with parameters | week1=4 week2=5 week3=4 weekdayFrom=2 weekdayTo=2 weekOrDayFrom=3 weekOrDayTo=3 isISOPeriod=true weekStartsAtWeekday=2 weekDayDefiningFirstWeek=5 |
If you want a Time Window open on the last weekend of each period:
| Field | Value |
|---|---|
| Period Function | System_FiscalPeriods |
| with parameters | week1=4 week2=4 week3=5 weekdayFrom=9 weekdayTo=9 weekOrDayFrom=5 weekOrDayTo=5 isISOPeriod=true weekStartsAtWeekday=2 weekDayDefiningFirstWeek=5 |
If you want your Time Window to open on the second and third Thursday of each period:
| Field | Value |
|---|---|
| Period Function | System_FiscalPeriods |
| with parameters | week1=4 week2=4 week3=5 weekdayFrom=5 weekdayTo=5 weekOrDayFrom=2 weekOrDayTo=3 isISOPeriod=true weekStartsAtWeekday=2 weekDayDefiningFirstWeek=5 |