PowerShell CLI 1.1 - Cmdlets - New-JobSchedulerHolidays

Name

New-JobSchedulerHolidays

SYNOPSIS

This cmdlet creates an XML holiday document that can be used to specifiy non-working days for start time calculation of jobs and orders.

SYNTAX

New-JobSchedulerHolidays [-Select] <String> [-Days] <Int32> [-Interval] <String> [[-Weekdays] <String[]>] [[-NonWorkingWeekdays] <String[]>] [[-FromDate] <DateTime>] [-ToDate] <DateTime> [[-HolidayFiles] <String[]>] [[-OutputFile] <String>] [-Append] [-Force] [<CommonParameters>]

DESCRIPTION

There are some use cases for start time calculation that exceed the
scope of run-time settings offered by JobScheduler:

* run a job each second first/last working day of a month, quarter or year
** JobScheduler considers the second first/last day (not: working day)
** JobScheduler considers working days based on individual calendars only after having applied the countdown
* run a job every second day during a period of e.g. a month, quarter, year
** JobScheduler re-calculates the run-time with the begin of a new period
** Periods start each day at midnight, therefore no longer periods can be used.

This cmdlet can be used to create an XML document with non-working days that are considered

* before counting a number of first/last working days.
* for start dates that are repeated each number of days, e.g. start a job every 3 days.

The recommended steps include to

* use this cmdlet to create a holiday output file with complementary non-working days.
** PS C:\> New-Holidays -Select last -Days 2 -Interval month -ToDate '2016-12-31'
* store the output file below the "live" directory with the subfolder that contains the respective job or order.
** PS C:\> New-Holidays -Select last -Days 2 -Interval month -ToDate '2016-12-31' -OutputFile ./my_jobs/my_jobs_holidays.xml
* have the job, order or schedule run-time
** specify a run-time rule for "any weekday", optionally limited to a number of weekdays as e.g. Mon-Fri.
** include the output file via <include/>, optionally in addition to some global holiday file like this:

<holidays>
<include live_file="public_holidays.xml"/>
<include live_file="some_order_holidays.xml"/>
</holidays>

With the assignment of the complementary holidays output file it is sufficient to set the start date
of a run-time to e.g. the 1st day before ultimo and to include the when_holiday="previous_non_holiday"
setting like this:

<ultimos>
<day day="1">
<period single_start="05:00" when_holiday="previous_non_holiday"/>
</day>
</ultimos>

PARAMETERS

Select

-Select <String>
Specifies the selection of days that is either counted from the begin or from the end of
the given interval, e.g. a week, a month, a year:

* first: select days to be counted from the begin of the interval
* last: select days to be counted from the end of the interval
* next: select days to be repeatedly counted within the interval

This parameter is used with the -Days and -Interval parameters to specify the direction in which
start dates are calculated for an interval, e.g. days at begin of each month or days before the end of each month.

Days

-Days <Int32>
Specifies the number of days starting from or ending with each interval
that are used to calculate the next start date.

This parameter is used with the -Select and -Interval parameters to specify the number of days that
are calculated for an interval.

Interval

-Interval <String>
Specifies the interval for which start dates are calculated:

* week: calculates the selected working days starting from or ending with each week
* month: calculates the selected working days starting from or ending with each month
* quarter: calculates the selected working days starting from or ending with each quarter
* year: calculates the selected working days starting from or ending with each year

This parameter is used with the -Select and -Days parameters to specify
the interval for which start dates are caluclated, e.g. a number of working days before end of each month.

Weekdays

-Weekdays <String[]>
Optionally specifies a list of weekdays for which jobs or job chains are not started, e.g.
due to run-time constraints.

The cmdlet will not create non-working days for the specified weekdays in order to avoid
redundancy as it is assumed that a run-time setting anyway excludes such dates.
When used with the -Force parameter then the cmdlet will generate such non-working days.

Weekdays kann be specified either by numbers 1..7 or by literals that are separated by a comma:

* -Weekdays 1,2,3,4,5
* -Weekdays Monday,Tuesday,Wednesday,Thursday,Friday

Both settings exclude Saturday and Sunday for which days the cmdlet will create non-working days.

NonWorkingWeekdays

-NonWorkingWeekdays <String[]>
Optionally specifies a list of weekdays for which jobs or job chains are not started, e.g.
due to run-time constraints.

The cmdlet will not create non-working days for the specified weekdays in order to avoid
redundancy as it is assumed that a run-time setting anyway excludes such dates.
When used with the -Force parameter then the cmdlet will generate such non-working days.

Weekdays kann be specified either by numbers 1..7 or by literals that are separated by a comma:

* -NonWorkingWeekdays 6,7
* -NonWorkingWeekdays Saturday,Sunday

Both settings specify Saturday and Sunday for which days the cmdlet will create non-working days.

This parameter is used as an alternative to the -Weekdays parameter. Both parameters provide the
same result, however, in some use cases it might be more appropriate to specify included weekdays
whereas for other use cases specifying excluded weekdays might be preferable.

FromDate

-FromDate <DateTime>
Specifies the lower bound of the date range for which non-working days are calculated.

If this parameter is not specified then the current date is assumed.

Default: current date

ToDate

-ToDate <DateTime>
Specifies the upper bound of the date range for which non-working days are calculated.

HolidayFiles

-HolidayFiles <String[]>
Optionally specifies the path and name for a number of global holiday files that are in use by JobScheduler.
Global non-working days from a holiday file are applied to the calculation of the next start date
by this cmdlet without being added to its output.

OutputFile

-OutputFile <String>
Optionally specifies an output file that contains the resulting XML configuration
for non-working days.

Append

-Append <SwitchParameter>
Optionally specifies the newly calculated non-working days to be appended
to an existing output file that is specified by use of the -OutputFile parameter.

Force

-Force <SwitchParameter>

RELATED LINKS

about_jobscheduler

EXAMPLES

-------------------------- EXAMPLE 1 --------------------------

PS > New-JobSchedulerHolidays -Select first -Days 2 -Interval year -NonWorkingWeekdays 6,7 -ToDate '2018-12-31' -Force

Calculates the non-working days for the second working day of each year from the current date until end of 2018. Saturday and Sunday are specified as non-working days and for which respective holiday dates are forced.

-------------------------- EXAMPLE 2 --------------------------

PS > New-JobSchedulerHolidays -Select first -Days 3 -Interval quarter -NonWorkingWeekdays 6,7 -FromDate '2016-01-01' -ToDate '2018-12-31' -Force

Calculates the non-working days for the third working day of each quarter from the specified date until end of 2018.

-------------------------- EXAMPLE 3 --------------------------

PS > New-JobSchedulerHolidays -Select first -Days 3 -Interval month -NonWorkingWeekdays 6,7 -FromDate '2016-01-01' -ToDate '2018-12-31' -Force

Calculates the non-working days for the third working day of each month from the specified date until end of 2018.

-------------------------- EXAMPLE 4 --------------------------

PS > New-JobSchedulerHolidays -Select last -Days 3 -Interval quarter -NonWorkingWeekdays 6,7 -FromDate '2016-01-01' -ToDate '2018-12-31' -Force

Calculates the non-working days for the third last working day of each quarter from the specified date until end of 2018.

-------------------------- EXAMPLE 5 --------------------------

PS > New-JobSchedulerHolidays -Select last -Days 3 -Interval month -NonWorkingWeekdays 6,7 -FromDate '2016-01-01' -ToDate '2018-12-31' -Force

Calculates the non-working days for the third last working day of each month from the specified date until end of 2018.

-------------------------- EXAMPLE 6 --------------------------

PS > New-JobSchedulerHolidays -Select last -Days 3 -Interval year -NonWorkingWeekdays 6,7 -FromDate '2016-01-01' -ToDate '2018-12-31' -Force

Calculates the non-working days for the third last working day of each year from the specified date until end of 2018.

-------------------------- EXAMPLE 7 --------------------------

PS > New-JobSchedulerHolidays -Select last -Days 2 -Interval week -NonWorkingWeekdays 6,7 -FromDate '2016-01-01' -ToDate '2018-12-31' -Force

Calculates the non-working days for the second last working day of each week (excluding Saturday and Sunday) from the specified date until end of 2018.

-------------------------- EXAMPLE 8 --------------------------

PS > $holidayFile = "$($env:ProgramFiles)\sos-berlin.com\jobscheduler\scheduler110\scheduler_data\config\live\globals\global_holidays.xml" New-JobSchedulerHolidays -Select first -Days 2 -Interval year -NonWorkingWeekdays 6,7 -FromDate '2016-01-01' -ToDate '2018-12-31' -HolidayFiles $holidayFile

Calculates the non-working days for the second working day of each year from the specified date until end of 2018 and considers non-working days from a global holidays file. No non-working days are created for Saturday and Sunday and for non-working days from the global holidays file.