PowerShell CLI 1.1 - Use Cases - Generate complementary non-working days for complex run-times

Starting Situation

• There are 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 first counts the number of days for the specified period and then applies settings for non-working days. Some use cases require the opposite sequence.
  • 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 day period at midnight.
    • Individual periods for job starts that use a previous period for start time calculation cannot be used.

• The below use cases implement a workaround for a situation.when non-working days should be considered
  • before counting for a number of first/last working days within a given period.
  • for job starts that are repeated after a number of days, e.g. start a job every 3 days.

Use of included files for non-working days

• JobScheduler considers non-working days that can be specified by use of the JOE Job Editor.
• In addition non-working days can be configured by individual XML files that are included with a run-time of a job, order or schedule:
  •  any number of files can be specified.
  • such files are specified with a relative path
    • a setting <include live_file="public_holidays.xml"/> addresses a file in the current folder (relative path).
    • a setting <include live_file="/globals/public_holidays.xml"/> addresses a file in a ./config/live/globals  (absolute path to the live folder).

    • a setting <include file="/tmp/globals/public_holidays.xml"/> addresses a file in a /tmp/globals folder (absolute path to the file system).

      Example for an order with non-working day include files Expand source

      <?xml version="1.0" encoding="iso-8859-1"?>
      <order  title="Run on 2nd last working day of month">
          <params />
          <run_time >
              <ultimos >
                  <day  day="1">
                      <period  single_start="05:00" when_holiday="previous_non_holiday"/>
                  </day>
              </ultimos>
              <holidays >
                  <include  live_file="public_holidays.xml"/>
                  <include  live_file="some_order_holidays.xml"/>
              </holidays>
          </run_time>
      </order>

  • The list of public holiday dates is provided with the public_holidays.xml file. Such a list of non-working dates is specific for a country or company and is created individually.

    List of public/company holidays Expand source

    <?xml version="1.0" encoding="iso-8859-1"?>
    <holidays >
        <holiday  date="2016-01-01"/>
        <holiday  date="2016-03-25"/>
        <holiday  date="2016-03-28"/>
        <holiday  date="2016-05-01"/>
        <holiday  date="2016-05-05"/>
        <holiday  date="2016-05-16"/>
        <holiday  date="2016-10-03"/>
        <holiday  date="2016-12-25"/>
        <holiday  date="2016-12-26"/>
    </holidays>

Use Cases

Start a job for the 2nd last working day of each month

• A working day is assumed for Mon-Fri, excluding Sat-Sun.
• The 2nd last working day is calculated excluding weekends and specific holiday dates as e.g. public holidays.

Cmdlet Execution

C:\PS> New-JobSchedulerHolidays -Select last -Days 2 -Interval month -NonWorkingWeekdays 6,7 -Force
-FromDate '2016-01-01' -ToDate '2018-12-31' -HolidayFile ./public_holidays.xml -OutputFile ./some_order_holidays.xml

• The New-JobSchedulerHolidays cmdlet calculates the non-working days for the 2nd last working day of each month within the specified date range (-FromDate, -ToDate).

• Saturday and Sunday are generally considered being non-working days (-NonWorkingWeekdays 6,7)

• The list of public holiday dates is provided with the public_holidays.xml file.

• By use of the -Force parameter all non-working days as specified by the -NonWorkingWeekdays and -HolidayFiles parameters are added to the output file.

• The list of complementary non-working days is created by the cmdlet with the output file some_order_holidays.xml. This list contains non-working days in addition to the above public holidays list and is calculated from the cmdlet parameters.

  List of complementary non-working days Expand source

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <holidays>
    <holiday date="2016-01-31" />
    <holiday date="2016-01-30" />
    <holiday date="2016-01-29" />
    <holiday date="2016-02-29" />
    <holiday date="2016-02-28" />
    <holiday date="2016-02-27" />
    <holiday date="2016-03-31" />
    <holiday date="2016-04-30" />
    <holiday date="2016-04-29" />
    <holiday date="2016-05-31" />
    <holiday date="2016-06-30" />
    <holiday date="2016-07-31" />
    <holiday date="2016-07-30" />
    <holiday date="2016-07-29" />
    <holiday date="2016-08-31" />
    <holiday date="2016-09-30" />
    <holiday date="2016-10-31" />
    <holiday date="2016-10-30" />
    <holiday date="2016-10-29" />
    <holiday date="2016-11-30" />
    <holiday date="2016-12-31" />
    <holiday date="2016-12-30" />
    <holiday date="2017-01-31" />
    <holiday date="2017-02-28" />
    <holiday date="2017-03-31" />
    <holiday date="2017-04-30" />
    <holiday date="2017-04-29" />
    <holiday date="2017-04-28" />
    <holiday date="2017-05-31" />
    <holiday date="2017-06-30" />
    <holiday date="2017-07-31" />
    <holiday date="2017-07-30" />
    <holiday date="2017-07-29" />
    <holiday date="2017-08-31" />
    <holiday date="2017-09-30" />
    <holiday date="2017-09-29" />
    <holiday date="2017-10-31" />
    <holiday date="2017-11-30" />
    <holiday date="2017-12-31" />
    <holiday date="2017-12-30" />
    <holiday date="2017-12-29" />
    <holiday date="2018-01-31" />
    <holiday date="2018-02-28" />
    <holiday date="2018-03-31" />
    <holiday date="2018-03-30" />
    <holiday date="2018-04-30" />
    <holiday date="2018-04-29" />
    <holiday date="2018-04-28" />
    <holiday date="2018-05-31" />
    <holiday date="2018-06-30" />
    <holiday date="2018-06-29" />
    <holiday date="2018-07-31" />
    <holiday date="2018-08-31" />
    <holiday date="2018-09-30" />
    <holiday date="2018-09-29" />
    <holiday date="2018-09-28" />
    <holiday date="2018-10-31" />
    <holiday date="2018-11-30" />
    <holiday date="2018-12-31" />
    <holiday date="2018-12-30" />
    <holiday date="2018-12-29" />
  </holidays>

Order Configuration

• To make an order use the list of complementary non-working days that is generated by the cmdlet the output file has to be included with the order like this:

  Example for an order with non-working day include files Expand source

  <?xml version="1.0" encoding="iso-8859-1"?>
  <order  title="Run on 2nd last working day of month">
      <params />
      <run_time >
          <ultimos >
              <day  day="1">
                  <period  single_start="05:00" when_holiday="previous_non_holiday"/>
              </day>
          </ultimos>
          <holidays >
              <include  live_file="public_holidays.xml"/>
              <include  live_file="some_order_holidays.xml"/>
          </holidays>
      </run_time>
  </order>

Start a job for the 2nd working day of each month

• A working day is assumed for Mon-Fri, excluding Sat-Sun.
• The 2nd working day is calculated excluding weekends and specific holiday dates as e.g. public holidays.

Cmdlet Execution

C:\PS> New-JobSchedulerHolidays -Select first -Days 2 -Interval month -NonWorkingWeekdays 6,7 -Force
-FromDate '2016-01-01' -ToDate '2018-12-31' -HolidayFile ./public_holidays.xml -OutputFile ./some_order_holidays.xml

• The New-JobSchedulerHolidays cmdlet calculates the non-working days for the 2nd working day of each month within the specified date range (-FromDate, -ToDate).

• Saturday and Sunday are generally considered being non-working days (-NonWorkingWeekdays 6,7).

• By use of the -Force parameter all non-working days as specified by the -NonWorkingWeekdays and -HolidayFiles parameters are added to the output file.

• The list of complementary non-working days is created by the cmdlet with the output file. This list contains non-working days in addition to the above public holidays list and is calculated from the cmdlet parameters.

  List of complementary non-working days Expand source

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <holidays>
    <holiday date="2016-01-01" />
    <holiday date="2016-01-02" />
    <holiday date="2016-01-03" />
    <holiday date="2016-01-04" />
    <holiday date="2016-02-01" />
    <holiday date="2016-03-01" />
    <holiday date="2016-04-01" />
    <holiday date="2016-04-02" />
    <holiday date="2016-04-03" />
    <holiday date="2016-05-01" />
    <holiday date="2016-05-02" />
    <holiday date="2016-06-01" />
    <holiday date="2016-07-01" />
    <holiday date="2016-07-02" />
    <holiday date="2016-07-03" />
    <holiday date="2016-08-01" />
    <holiday date="2016-09-01" />
    <holiday date="2016-10-01" />
    <holiday date="2016-10-02" />
    <holiday date="2016-10-03" />
    <holiday date="2016-10-04" />
    <holiday date="2016-11-01" />
    <holiday date="2016-12-01" />
    <holiday date="2017-01-01" />
    <holiday date="2017-01-02" />
    <holiday date="2017-02-01" />
    <holiday date="2017-03-01" />
    <holiday date="2017-04-01" />
    <holiday date="2017-04-02" />
    <holiday date="2017-04-03" />
    <holiday date="2017-05-01" />
    <holiday date="2017-06-01" />
    <holiday date="2017-07-01" />
    <holiday date="2017-07-02" />
    <holiday date="2017-07-03" />
    <holiday date="2017-08-01" />
    <holiday date="2017-09-01" />
    <holiday date="2017-09-02" />
    <holiday date="2017-09-03" />
    <holiday date="2017-10-01" />
    <holiday date="2017-10-02" />
    <holiday date="2017-11-01" />
    <holiday date="2017-12-01" />
    <holiday date="2017-12-02" />
    <holiday date="2017-12-03" />
    <holiday date="2018-01-01" />
    <holiday date="2018-02-01" />
    <holiday date="2018-03-01" />
    <holiday date="2018-04-01" />
    <holiday date="2018-04-02" />
    <holiday date="2018-05-01" />
    <holiday date="2018-06-01" />
    <holiday date="2018-06-02" />
    <holiday date="2018-06-03" />
    <holiday date="2018-07-01" />
    <holiday date="2018-07-02" />
    <holiday date="2018-08-01" />
    <holiday date="2018-09-01" />
    <holiday date="2018-09-02" />
    <holiday date="2018-09-03" />
    <holiday date="2018-10-01" />
    <holiday date="2018-11-01" />
    <holiday date="2018-12-01" />
    <holiday date="2018-12-02" />
    <holiday date="2018-12-03" />
  </holidays>

Order Configuration

• To make an order use the list of complementary non-working days that is generated by the cmdlet the output file has to be included with the order like this:

  Example for an order with non-working day include files Expand source

  <?xml version="1.0" encoding="iso-8859-1"?>
  <order  title="Run on each 2nd working day of month">
      <params />
      <run_time >
          <monthdays >
              <day  day="2">
                  <period  single_start="05:00" when_holiday="next_non_holiday"/>
              </day>
          </monthdays>
          <holidays >
              <include  live_file="public_holidays.xml"/>
              <include  live_file="some_order_holidays.xml"/>
          </holidays>
      </run_time>
  </order>

Start a job for each 2nd working day of a year

• A working day is assumed for Mon-Fri, excluding Sat-Sun.
• The 2nd working day is calculated excluding weekends and specific holiday dates as e.g. public holidays.

Cmdlet Execution

C:\PS> New-JobSchedulerHolidays -Select next -Days 2 -Interval year -NonWorkingWeekdays 6,7 -Force
-FromDate '2016-01-01' -ToDate '2016-12-31' -HolidayFile ./public_holidays.xml -OutputFile ./some_order_holidays.xml

• The New-JobSchedulerHolidays cmdlet calculates the non-working days for each 2nd working day during a year within the specified date range (-FromDate, -ToDate).

• By use of the -Force parameter all non-working days as specified by the -NonWorkingWeekdays and -HolidayFiles parameters are added to the output file.

• The list of complementary non-working days is created by the cmdlet with the output file. This list contains non-working days in addition to the above public holidays list and is calculated from the cmdlet parameters.

  List of complementary non-working days Expand source

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <holidays>
    <holiday date="2016-01-01" />
    <holiday date="2016-01-02" />
    <holiday date="2016-01-03" />
    <holiday date="2016-01-04" />
    <holiday date="2016-01-06" />
    <holiday date="2016-01-08" />
    <holiday date="2016-01-09" />
    <holiday date="2016-01-10" />
    <holiday date="2016-01-12" />
    <holiday date="2016-01-14" />
    <holiday date="2016-01-16" />
    <holiday date="2016-01-17" />
    <holiday date="2016-01-18" />
    <holiday date="2016-01-20" />
    <holiday date="2016-01-22" />
    <holiday date="2016-01-23" />
    <holiday date="2016-01-24" />
    <holiday date="2016-01-26" />
    <holiday date="2016-01-28" />
    <holiday date="2016-01-30" />
    <holiday date="2016-01-31" />
    <holiday date="2016-02-01" />
    <holiday date="2016-02-03" />
    <holiday date="2016-02-05" />
    <holiday date="2016-02-06" />
    <holiday date="2016-02-07" />
    <holiday date="2016-02-09" />
    <holiday date="2016-02-11" />
    <holiday date="2016-02-13" />
    <holiday date="2016-02-14" />
    <holiday date="2016-02-15" />
    <holiday date="2016-02-17" />
    <holiday date="2016-02-19" />
    <holiday date="2016-02-20" />
    <holiday date="2016-02-21" />
    <holiday date="2016-02-23" />
    <holiday date="2016-02-25" />
    <holiday date="2016-02-27" />
    <holiday date="2016-02-28" />
    <holiday date="2016-02-29" />
    <holiday date="2016-03-02" />
    <holiday date="2016-03-04" />
    <holiday date="2016-03-05" />
    <holiday date="2016-03-06" />
    <holiday date="2016-03-08" />
    <holiday date="2016-03-10" />
    <holiday date="2016-03-12" />
    <holiday date="2016-03-13" />
    <holiday date="2016-03-14" />
    <holiday date="2016-03-16" />
    <holiday date="2016-03-18" />
    <holiday date="2016-03-19" />
    <holiday date="2016-03-20" />
    <holiday date="2016-03-22" />
    <holiday date="2016-03-24" />
    <holiday date="2016-03-25" />
    <holiday date="2016-03-26" />
    <holiday date="2016-03-27" />
    <holiday date="2016-03-28" />
    <holiday date="2016-03-30" />
    <holiday date="2016-04-01" />
    <holiday date="2016-04-02" />
    <holiday date="2016-04-03" />
    <holiday date="2016-04-05" />
    <holiday date="2016-04-07" />
    <holiday date="2016-04-09" />
    <holiday date="2016-04-10" />
    <holiday date="2016-04-11" />
    <holiday date="2016-04-13" />
    <holiday date="2016-04-15" />
    <holiday date="2016-04-16" />
    <holiday date="2016-04-17" />
    <holiday date="2016-04-19" />
    <holiday date="2016-04-21" />
    <holiday date="2016-04-23" />
    <holiday date="2016-04-24" />
    <holiday date="2016-04-25" />
    <holiday date="2016-04-27" />
    <holiday date="2016-04-29" />
    <holiday date="2016-04-30" />
    <holiday date="2016-05-01" />
    <holiday date="2016-05-03" />
    <holiday date="2016-05-05" />
    <holiday date="2016-05-06" />
    <holiday date="2016-05-07" />
    <holiday date="2016-05-08" />
    <holiday date="2016-05-10" />
    <holiday date="2016-05-12" />
    <holiday date="2016-05-14" />
    <holiday date="2016-05-15" />
    <holiday date="2016-05-16" />
    <holiday date="2016-05-17" />
    <holiday date="2016-05-19" />
    <holiday date="2016-05-21" />
    <holiday date="2016-05-22" />
    <holiday date="2016-05-23" />
    <holiday date="2016-05-25" />
    <holiday date="2016-05-27" />
    <holiday date="2016-05-28" />
    <holiday date="2016-05-29" />
    <holiday date="2016-05-31" />
    <holiday date="2016-06-02" />
    <holiday date="2016-06-04" />
    <holiday date="2016-06-05" />
    <holiday date="2016-06-06" />
    <holiday date="2016-06-08" />
    <holiday date="2016-06-10" />
    <holiday date="2016-06-11" />
    <holiday date="2016-06-12" />
    <holiday date="2016-06-14" />
    <holiday date="2016-06-16" />
    <holiday date="2016-06-18" />
    <holiday date="2016-06-19" />
    <holiday date="2016-06-20" />
    <holiday date="2016-06-22" />
    <holiday date="2016-06-24" />
    <holiday date="2016-06-25" />
    <holiday date="2016-06-26" />
    <holiday date="2016-06-28" />
    <holiday date="2016-06-30" />
    <holiday date="2016-07-02" />
    <holiday date="2016-07-03" />
    <holiday date="2016-07-04" />
    <holiday date="2016-07-06" />
    <holiday date="2016-07-08" />
    <holiday date="2016-07-09" />
    <holiday date="2016-07-10" />
    <holiday date="2016-07-12" />
    <holiday date="2016-07-14" />
    <holiday date="2016-07-16" />
    <holiday date="2016-07-17" />
    <holiday date="2016-07-18" />
    <holiday date="2016-07-20" />
    <holiday date="2016-07-22" />
    <holiday date="2016-07-23" />
    <holiday date="2016-07-24" />
    <holiday date="2016-07-26" />
    <holiday date="2016-07-28" />
    <holiday date="2016-07-30" />
    <holiday date="2016-07-31" />
    <holiday date="2016-08-01" />
    <holiday date="2016-08-03" />
    <holiday date="2016-08-05" />
    <holiday date="2016-08-06" />
    <holiday date="2016-08-07" />
    <holiday date="2016-08-09" />
    <holiday date="2016-08-11" />
    <holiday date="2016-08-13" />
    <holiday date="2016-08-14" />
    <holiday date="2016-08-15" />
    <holiday date="2016-08-17" />
    <holiday date="2016-08-19" />
    <holiday date="2016-08-20" />
    <holiday date="2016-08-21" />
    <holiday date="2016-08-23" />
    <holiday date="2016-08-25" />
    <holiday date="2016-08-27" />
    <holiday date="2016-08-28" />
    <holiday date="2016-08-29" />
    <holiday date="2016-08-31" />
    <holiday date="2016-09-02" />
    <holiday date="2016-09-03" />
    <holiday date="2016-09-04" />
    <holiday date="2016-09-06" />
    <holiday date="2016-09-08" />
    <holiday date="2016-09-10" />
    <holiday date="2016-09-11" />
    <holiday date="2016-09-12" />
    <holiday date="2016-09-14" />
    <holiday date="2016-09-16" />
    <holiday date="2016-09-17" />
    <holiday date="2016-09-18" />
    <holiday date="2016-09-20" />
    <holiday date="2016-09-22" />
    <holiday date="2016-09-24" />
    <holiday date="2016-09-25" />
    <holiday date="2016-09-26" />
    <holiday date="2016-09-28" />
    <holiday date="2016-09-30" />
    <holiday date="2016-10-01" />
    <holiday date="2016-10-02" />
    <holiday date="2016-10-03" />
    <holiday date="2016-10-05" />
    <holiday date="2016-10-07" />
    <holiday date="2016-10-08" />
    <holiday date="2016-10-09" />
    <holiday date="2016-10-11" />
    <holiday date="2016-10-13" />
    <holiday date="2016-10-15" />
    <holiday date="2016-10-16" />
    <holiday date="2016-10-17" />
    <holiday date="2016-10-19" />
    <holiday date="2016-10-21" />
    <holiday date="2016-10-22" />
    <holiday date="2016-10-23" />
    <holiday date="2016-10-25" />
    <holiday date="2016-10-27" />
    <holiday date="2016-10-29" />
    <holiday date="2016-10-30" />
    <holiday date="2016-10-31" />
    <holiday date="2016-11-02" />
    <holiday date="2016-11-04" />
    <holiday date="2016-11-05" />
    <holiday date="2016-11-06" />
    <holiday date="2016-11-08" />
    <holiday date="2016-11-10" />
    <holiday date="2016-11-12" />
    <holiday date="2016-11-13" />
    <holiday date="2016-11-14" />
    <holiday date="2016-11-16" />
    <holiday date="2016-11-18" />
    <holiday date="2016-11-19" />
    <holiday date="2016-11-20" />
    <holiday date="2016-11-22" />
    <holiday date="2016-11-24" />
    <holiday date="2016-11-26" />
    <holiday date="2016-11-27" />
    <holiday date="2016-11-28" />
    <holiday date="2016-11-30" />
    <holiday date="2016-12-02" />
    <holiday date="2016-12-03" />
    <holiday date="2016-12-04" />
    <holiday date="2016-12-06" />
    <holiday date="2016-12-08" />
    <holiday date="2016-12-10" />
    <holiday date="2016-12-11" />
    <holiday date="2016-12-12" />
    <holiday date="2016-12-14" />
    <holiday date="2016-12-16" />
    <holiday date="2016-12-17" />
    <holiday date="2016-12-18" />
    <holiday date="2016-12-20" />
    <holiday date="2016-12-22" />
    <holiday date="2016-12-24" />
    <holiday date="2016-12-25" />
    <holiday date="2016-12-26" />
    <holiday date="2016-12-27" />
    <holiday date="2016-12-29" />
  </holidays>

Order Configuration

• To make an order use the list of complementary non-working days that is generated by the cmdlet the output file has to be included with the order like this:

  Example for an order with non-working day include files Expand source

  <?xml version="1.0" encoding="iso-8859-1"?>
  <order  title="Run on each 2nd working day of month">
      <params />
      <run_time >
          <weekdays >
              <day  day="1 2 3 4 5">
                  <period  single_start="05:00" when_holiday="next_non_holiday"/>
              </day>
          </weekdays>
          <holidays >
              <include  live_file="public_holidays.xml"/>
              <include  live_file="some_order_holidays.xml"/>
          </holidays>
      </run_time>
  </order>

Hints

How to check start times

• Start times can be visualized from the JOC GUI.
• In addition the Show-JobSchedulerCalendar and Get-JobSchedulerCalendar cmdlets are available.

Cmdlet Execution

• The cmdlet can be parameterized e.g. with the job chain for which start times should be calculated like this:

  C:\PS> Show-JobSchedulerCalendar -JobChain /holidays/some_job_chain -ToDate 2016-12-31

• The cmdlet calculates the next start times for the specified date range (-FromDate, -ToDate). If no -FromDate is specified then the current date is assumed.

Cmdlet Output

• The sample output from the above cmdlet execution could look like this:

  Sample cmdlet output for order start times

  ________________________________________________________________________
  Orders by start-time
  at 2016-08-29T03:00:00Z order some_order job chain /holidays/some_job_chain
  at 2016-09-28T03:00:00Z order some_order job chain /holidays/some_job_chain
  at 2016-10-29T03:00:00Z order some_order job chain /holidays/some_job_chain
  at 2016-11-28T04:00:00Z order some_order job chain /holidays/some_job_chain
  at 2016-12-30T04:00:00Z order some_order job chain /holidays/some_job_chain
  
  ________________________________________________________________________

How to generate complementary non-working days by a job

• The above use cases for the New-JobSchedulerHolidays cmdlet can be automated by use of 
  • a PowerShell Job that runs with an Agent on the same server that the Master is operated for
  • the PowerShell Command Line Interface

• A sample job that creates complementary non-working days as explained with the above Start a job for each 2nd working day of a year chapter could look like this:

  Example for a standalone job that generates complementary non-working days Expand source

  <?xml version="1.0" encoding="iso-8859-1"?>
  
  <job  process_class="Agent_01" stop_on_error="no">
      <script  language="powershell">
          <![CDATA[
  Import-Module JobScheduler
  
  New-JobSchedulerHolidays -Select next -Days 2 -Interval year -NonWorkingWeekdays 6,7 -Force -ToDate (Get-Date).AddYears(1) -HolidayFiles "$($spooler_job.configuration_directory())/public_holidays.xml" -OutputFile "$($spooler_job.configuration_directory())/some_order_holidays.xml"
  
  Show-JobSchedulerCalendar -Directory $spooler_job.folder_path() -ToDate (Get-Date).AddYears(1)
          ]]>
      </script>
      <run_time />
  </job>

• This job parameterizes the New-JobSchedulerHolidays cmdlet to calculate complementary non-working days for one year starting from the date when the job starts.
• The output file is written to the current job configuration folder, an existing file will be overwritten.
• Subsequently the start times for jobs and job chains in the current job configuration folder are displayed by use of the Show-JobSchedulerCalendar cmdlet.

See also

• PowerShell Command Line Interface 1.1 - Introduction
• PowerShell Jobs