Current Situation

There is no calendar management in JOC Cockpit. Defining business calendars or non-working days can be done with the run-time editor but not by using a business calendar.

Desired Behaviour

Calendar Management

A new calendar function should be implemented to enhance the options when defining the run time

The function will provide a list of calendars. Each calendar can be a working day calendar or a non working day calendar.

The configuration

• Is stored in the reporting database
• Can have a category
  • • The category is null if no categorie has been selected
    • The category e.g. can be „non_working_days“ or „working_days“ or anything else
• contains the selected frequencies for add and remove days

Design Decisions

• The configuration for calendars contain the frequencies.
• At the assigning process the list of days that results from these frequencies will be calculated.
  • For scheduler2, the id of the underlying calendar should be part of the element <date>
• The list of days is represented in the runtime as a list of <date> elements.
• With this approach
  • it is possible to see the frequencies during the calendar editing process
  • it is easy to add new types of frequency (e.g. last working day of a quarter) if neccessary
  • no changes are necessary in the scheduler engine.

Defining non working days

• Non working days are defined as a calender with the category „non working days“. All features of calendar definition is available when defining non working days.
• Each calendar can be used as a non working days calendar
  • It easier for the user if non working days calendars are classified with a category (e.g. „non working days“) but all calendars can be used as „non working day“ calendars.
• There is no difference for calendars that represents non working days or working days.
• The handling and user interactions are the same for both types of calendars
• The user can assign the calendar to a category to describe the intended use of the calendar

Functions for Configuration Management

Frequencies

There are the following frequencies:

Known frequencies

• Any weekdays
• Every day
  • Which is a special case of days of Any weekdays
• Specific days
• Specific days of week
• first monday in the month
• last tues in the month
• Ultimos
• Last day in the month
• Days in a month
• First day in the month

New frequencies

• n.th working day
• Last n.th working day
• every x days starting with day=z
• every x weeks starting with day=z
• every x months starting day=z
• selected days from a national non working day calendar.
• … this list can be continued

Considerations for frequencies

• Every frequency has a list of periods.
• It is possible to define an interval for each frequency from a to b where a and b are dates
• Defining the frequencies will result in a year calendar that contains all days from „included days from frequency“ minus the days from „excluded days from frequency“
• When a frequency is member of <included> element and one day is manually removed from the year calendar, this day becomes a member of the <excluded><frequencies><dates> element of the frequency.

Generating dates when Jobs/Orders should run

The dates when Jobs/Orders can run a calculated.

• When editing a calendar to show the result of a specific frequency
• When assing a calender to a run time in the run time editor to create the list of <date> for the run time.

This list of dates is only stored in the run time after a calender has been assigned. There is no relation back from a run time to the used calendar. When JobScheduler Master would accept a <date calendar=“myCalendar“ date="2017-08-15"> element it would be possible to remove all <date> elements from a run time that have been creating during the assignment of the calendar „myCalendar“

Web Service Functions for Calendar Management

The JOC Web Service will provide the functions for retrieving and storing calendars in the file system.

Store and retrieve calendars

GetListOfCalendars()
returns a list of calendar names with path and category.

GetListOfDates(calendar)
returns a list of dates calculated from the given dates

GetCalendar
body: the name and path of the calendar to be read
returns the content of one calendar as a json object.

WriteCalendar()
body: the json representation of the calendar
writes the calendar as a json string to the reporting database

GetCategories
returns the list of known calendar categories

GUI Functions

The JOC GUI provides the function

• Create/Edit Calendars
  • Permissions
    • sos:products:joc_cockpit:calendar:view:status
    • sos:products:joc_cockpit:calendar:edit:change
    • sos:products:joc_cockpit:calendar:edit:delete
    • sos:products:joc_cockpit:calendar:edit:create
    • sos:products:joc_cockpit:calendar:assign:change
    • sos:products:joc_cockpit:calendar:assign:nonworking
    • sos:products:joc_cockpit:calendar:assign:runtime

• • Calendars are ressources
  • The calendar management will be located in the ressources view.
  • The gui shows the list of known calendars
  • The list can be filtered by the category
  • One calendar will be selected by the user
  • Or the user creates a new calendar
    • Filling out the name and category of the calendar
  • After selecting the calendar
    • A list of the frequencies will be shown
    • New frequencies can be added
    • Frequencies can be removed
    • Frequencies can be changed
    • A year calendar with all days will be shown.
  • Selecting a frequency will activate the days that are calculated from the frequency
  • When Selecting the „all“ node, all days will be shown in the calendar
    • days from <included> minus days from <excluded>
  • It is possible to deselect single days
    • these days will be moved to the <excluded><frequencies><dates> element
  • It is possible to add single days
    • These days will be added to the <included><frequencies><dates> element
• Assign non working days to a run time
  • During the assigning process the rules of the calendar will be calculated to a list of <date>
  • Periods are assigned to each frequency

One JobSchedule instance can have several defined calendars. To use them a new function „assign calendar“ is added to the run time editor.

Run time editor

• In the run time editor is a new function called „Assign calendar“.
  • Show the list of calendars by categories
  • User selects a calendar
  • The days with the containing frequencies in „included“ will be calculated.
  • The days containing frequencies in „excluded“ will be calculated and removed from the list of days from <included>
  • Show the year calendar
  • Give the option to remove and add additional days
  • Give the option to add one or more non working day calendars
    • Non working days already can be assigned in the calendar in the <excluded> element. But it also possible to substract a calender that contains the non working days from the calendar with the working days during the assign process.
    • Show the list of calendars by categories
    • Select a calendar
    • Calculate the days with the containing frequencies in „included“
    • Remove the days calculated with the containing frequencies in „excluded“
    • Give the option to remove and add additional days
    • Substract the resulting days from the assigned calendar.
  • Create a runtime with a list of <date date="2017-08-13"><period single_start="12:00"/></date>
  • It is possible to add the period (or a number of periods) here.
  • The period can be assigned to the frequency. That means that all calculated days of the frequency will have this period.
  • The period can be assigned to a single day of the calculated days by adding a period to the <date> section. That will overwrite a period that is assigned to a frequency.

Calendar Management with JobScheduler2

The functions for Configuration Management, Web Service Functions for Calendar Management are the same when using calendars for JobScheduler2
The Web Service Functions for Order Management will be added in JobScheduler2.

Generate Orders for start times.

• This web service will add an order for each start of an order on the agent
• Orders will be created for a given number of days
• The start time of an order is defined by the day and a single start.
• The period intervall start/start will be calculated to orders with single starts as many as necessary for the given interval
• The period intervall end/start will no longer be supported.

Manage orders

• to read, update, delete orders that already have created
• to create new orders „on the fly“ for a specific day and time
• show the list of planned orders
• this will substitute the <calendar> xml command
• this will be used for the daily plan view to visualize the status of a planned order.

API specification

JOC API