Defining Advanced Execution Times with Period Functions
Redwood Server features rich calendaring possibilities; time windows offer great flexibility while remaining easy to define. However, sometimes complex calculations are required to determine if certain conditions are met for a time window to be open, Easter for example. For this matter it is possible to create period functions. Period functions are boolean functions used in time windows that calculate when a time window is supposed to be open or closed. Period functions are complex functions written in RedwoodScript, stored in the Repository, that are used in time windows to calculate the dates and times that a time interval is open.
When you import SAP Calendars (like the Factory and Holiday calendars), these become available as period functions.
You can also define your own period functions, however, since all time windows using a period function share the same instance of a period function, parameter values can be cached for performance reasons. You must be very careful and check your parameters.
The following period functions are built-in:
| Period Function | Description |
|---|---|
| SAP_FactoryCalendar | Use the SAP calendar from an SAP instance to schedule SAP jobs; the calendaring data needs to be imported from the instance |
| SAP_HolidayCalendar | Use the SAP calendar from an SAP instance to schedule SAP jobs; the calendaring data needs to be imported from the instance |
| System_InDayRecurrence | Recurrence within a day |
| System_Easter | Calculates Easter or Easter-based holidays |
| System_FiscalPeriods | Calculates open days based on periods in a fiscal year. |
note
You need the scripting module, which requires the Module.Scripting license key, to be able to create period functions.
Caching Objects in Period Functions
You should not cache SchedulerEntities, such as Time Windows, in period functions as these might have a long life-time or the dispatcher may refresh the session, causing JCS-122017: Trying to use non-attached object TimeWindow errors, for a time window in this example.
Easter Period Function
The easter period function accepts one dayNumber parameter, which is the offset to easter Sunday.
No parameter or dayNumber=0 means easter Sunday.
SAP Calendars
SAP calendars are imported and converted to period functions to be used in time windows. Period functions of SAP calendars take arguments, as 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, can be found in the output file of the SAP_ImportCalendar process. |
You should only specify instances for which you have imported the calendar with the SAP_ImportCalendar process definition and the specific calendar ID must exist in that SAP instance. Use the Opens at tab of the time window edit screen to ensure you are using the correct values.
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 in 1 five- and 2 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). |
note
The period function parameters are case-sensitive.
note
All parameters must be filled or you will not get the desired result.
Using Fiscal Period Functions
When you create a fiscal period function, you first specify the number weeks of your three periods, for example week1=4 week2=4 week3=5.
Next, you 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 workweek 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, you specify when the time frame occurs in your 3 periods using the weekOrDayFrom and weekOrDayTo parameters, for example weekOrDayFrom=5 and weekOrDayTo=5, meaning the last workweek of each period ( 5 is greater than 4 ).
If you only want to have the process run 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=8weekdayTo=8weekOrDayFrom=1weekOrDayTo=5 | weekdayFrom=10weekdayTo=10weekOrDayFrom=1weekOrDayTo=1 |
| weekdayFrom=8weekdayTo=8weekOrDayFrom=1weekOrDayTo=10 | weekdayFrom=10weekdayTo=10weekOrDayFrom=1weekOrDayTo=2 |
When 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 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.
note
When the duration >= interval, the period function is always open. When EndTime=0, the EndTime will be the start of the next day.
Context-Menu
Period functions support the following context-menu actions:
| Action | Description |
|---|---|
| Edit Security | Edit the security of the period function |
| Duplicate | Make a copy of the period function to create a similar one |
| Delete | Delete the period function |
| Export > Export | Export the period function into a CAR file |
| Export > Export with related objects | Export the period function into a CAR file including referenced objects |
| Promote > Promote to system | Promote the object to a remote system |
| Promote > Edit further then promote | Edit the export rule set prior to promoting |
| Promote | Promote the period function to another Redwood Server instance |
| Edit | Edit the period function |
| Show permalinks | Show links that can be used from third party applications to link to the object |
| Add to navigation bar | Add the current object to the navigation bar |
| New period function | Create a new period function |
| Filter > New Filter | Create a new period function filter |
| Filter > Edit Filter | Edit current period function filter |
| Filter > Delete | Delete current period function filter |
| Filter > Duplicate Filter | Create a copy of the filter |
| Filter > Export Filter | Export the filter into a CAR file |
| Filter > Add to navigation bar | Add the filter to a navigation bar |
| Filter > Create filter from search | Create a filter from the current IntelliSearch query |
Finding Period Functions
You can search for period functions using filters and the Search Period Functions box on the Period Functions tab. This box is known as the IntelliSearch box and located under your username on the top right-hand side of the user interface. Filters allow you to specify a list of objects with static criteria. IntelliSearch allows you to specify complex queries in a simple way using prefixes. Prefixes are used to specify which property you are searching in and have short as well as long syntaxes. For example, if you want to display all period functions with the term import in the comment, you would use the search criteria as follows:
c:import
You can search more than one property, as follows:
c:import n:Bi
note
No spaces should be entered before or after the colon (: ).
See the Advanced Object Search for more information.
The following table illustrates the available prefixes for period functions:
| Prefixes | Description |
|---|---|
| n, name | searches the name property |
| c, comm, comment | searches the documentation property |
| d, desc, description | searches the description property |
| a, application | searches the application property |
| cb, changedbefore | (internal) search for period functions that changed before a certain ISO-8601 period |
Deleting Period Functions
You can only delete period functions when no other objects relate to them. For example, if there are time windows that use the 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 the period function in Related Objects in the lower detail pane and on the show page.
The table in related objects contains three columns:
- Type - the type of object with a link to it
- Related Object - the name of the object with a link to it
- Used As - objects can sometimes be used in different roles
Security
| Privilege | Description |
|---|---|
| PeriodFunction.Create | Create period functions |
| PeriodFunction.Delete | Delete period functions |
| PeriodFunction.Edit | Edit period functions |
| PeriodFunction.View | Access period functions |
You can grant privileges on two levels, Access and Admin; a privilege granted on Admin level allows the grantee to grant the privilege to other users. These privileges can be granted per partition or system-wide.
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
You want a time window to open on the third Monday of each period
| Field | Value |
|---|---|
| Period Function | System_FiscalPeriods |
| with parameters | week1=4week2=5week3=4weekdayFrom=2weekdayTo=2weekOrDayFrom=3weekOrDayTo=3isISOPeriod=trueweekStartsAtWeekday=2weekDayDefiningFirstWeek=5 |
You want a time window open on the last weekend of each period
| Field | Value |
|---|---|
| Period Function | System_FiscalPeriods |
| with parameters | week1=4week2=4week3=5weekdayFrom=9weekdayTo=9weekOrDayFrom=5weekOrDayTo=5isISOPeriod=trueweekStartsAtWeekday=2weekDayDefiningFirstWeek=5 |
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=4week2=4week3=5weekdayFrom=5weekdayTo=5weekOrDayFrom=2weekOrDayTo=3isISOPeriod=trueweekStartsAtWeekday=2weekDayDefiningFirstWeek=5 |
PeriodFunction