In JAMS V7.0.1561 and later, scheduling functionality has been completely upgraded in JAMS with the introduction of Calendar definitions - collections of Date Types that also offer Security Controls.
In this Article:
- Understanding How Calendars Work
- The Updated Calendar View
- Adding a new Calendar
- Adding a new Date Type
- Adding a new Date
Advanced Date Concepts
Understanding how Calendars Work
Calendars in JAMS follow a simple architecture with three main components -
- Calendars, which are made up of Date Types
- Date Types, which exist in Calendars and are made up of Date Definitions
- Date Definitions, which exist in Date Types, and are the actual defined days
(E.g. July 4th, October 31st, etc.)
Calendars are the highest level of organization for dates in JAMS. Users can create any number of Calendars, as long as the Calendars are given unique names. JAMS V7.0.1561 and later ships with a single predefined "Default" Calendar. Users can set Calendar Scope on the Folder and Job level with the Calendar Property. Calendars also offer Security Settings, with ACEs and options for Change, Control, Delete, and Inquire settings.
NOTE: Users upgrading to JAMS V7.0.1561 or later will have all their Date Types automatically put into the "Default" Calendar.
Date Types are the intermediary level of date organization. Date Types are best described as logical collections of Date Definitions and Date Type references that reside in Calendars. Any number of Date Types may be nested in each Calendar, and contain any number of Date Definitions and Date Type references. Date Types are defined as either Non-Continuous (E.g. Holidays, Birthdays) or Continuous (E.g. Fiscal_Quarters). Users can reference Date Types within Schedule Elements.
In JAMS V7.0.1678 and later, Date Types can reference other Date Types. This allows users to create dynamic references to other Date Types that will reflect changes to those other types. For instance, if the CompanyHolidays Date Type references the USHolidays Date Type and the dates change, that change will be immediately reflected in the CompanyHolidays Date Type.
E.g. the "UK_Holidays" Date Type could contain 15 individual date definitions, reference the "RegionalHolidays" Date Type, and reside in the "Company Holidays" Calendar.
Specific Types are named collections of dates within a Date Type. Specific Types are generally used for continuous dates. For example, a Fiscal 2018 Date Type might contain Specific Types of Q1_2018, Q2_2018, Q3_2018, and Q4_2018. Users can reference Specific Types within Schedule Elements.
NOTE: To add Dates to a Specific Type, set the Specific Type value on the Date Definition.
Date Definitions are the most granular level of date organization, and represent the actual defined days within a Date Type. Any number of Date Definitions may be added to any Date Type. Users may define Dates as Workdays or Non-Workdays, which will comply with workday and non-workday scheduling set on Jobs and Folders. If the Date Type a date belongs to has Specific Types, users may define a Specific Type on the date.
Example:
WidgetCo is a global company that needs some Jobs to skip (not run on) US Holidays, and other Jobs to skip UK Holidays.
First, they create a "Company Holidays" Calendar. This is the parent Calendar that will contain the Date Types for the holidays their different offices observe.
Within the Company Holidays Calendar, they create a "USHolidays" Date Type, and a "UKHolidays" Date Type. These Date Types will store the holidays specific to each office.
In the USHolidays Date type, they add Date Definitions for each US Holiday observed - January 1st, July 4th, etc.; then repeat the process for the UK Holidays.
With the Dates, Date Types, and Calendar configured, WidgetCo is ready to set Calendar Scope on the Job and Folder level. They add the Calendar Property on the desired Job or Folder, then set the Calendar value to the corresponding Calendar.
With the calendar set, WidgetCo can set their Schedule Element's Except for Date to reference the USHolidays or UKHolidays date types, ensuring their Jobs won't be automatically scheduled on the given holidays.
The Updated Calendar View
The updated Calendar view contains three sections:
- A Calendar navigator
- A Date List
- An outlook-style Visual Calendar
Calendar Navigator
The Calendar Navigator is the control for the Date List and Visual Calendar sections. Selected (checked) Calendars and Date Types will be displayed in the date list grid and the visual calendar. The navigator is responsive, so checking or un-checking calendars and date types in the Calendar Navigator will be reflected on the Date List and Visual Calendar in real time.
Date List
The Date List is a grid-style display of the dates within any Date Types selected in the Calendar Navigator. The Date List grid displays the actual dates alongside their corresponding Date Type and Calendar. The same sorting, grouping, and filtering options available on all other JAMS grid views are available in the Date List. Double-clicking any Dates in the list will open the Date Definition dialog. Right-clicking any date provides a drop-down with options to Copy the date to another Date Type, Edit the Date Definition, and Delete the date.
Visual Calendar
The visual calendar acts much like an outlook calendar, with date names and colors represented on the given days where the dates are defined. Users can navigate through dates by scrolling, with the forward and back buttons at the top of the calendar, or by using the arrow buttons in the middle of the calendar display to navigate to the next date or previous date defined on the calendar. Users may also adjust the scale of the visual calendar with "Ctrl+Scroll". Right-clicking on any dates in the Visual Calendar will give a drop-down list with options to copy, delete, or edit the Date Definition.
NOTE: If displaying referenced Date Types, users may not have permissions to copy, delete, or edit the dates displayed in the visual calendar.
Adding a new Calendar
- Navigate to the Calendars shortcut, then use the Add Calendar button to open the Add a Calendar Definition dialog.
- In the dialog, define the Calendar's Name, add a description (optional), and set a Color for the calendar.
NOTE: Users may select from System Colors, Web Colors, or Custom colors for Calendar coloring. - Click the Ok button. The Calendar Properties dialog will open by default.
- Set Security options as desired, then Save & Close the Calendar.
Adding a new Date Type
- Navigate to the Calendars shortcut, then use the Add Date Type button to open the Add a Date Type Definition dialog.
- In the dialog, select the Parent Calendar, define the Date Type's Name, add a description (optional), and define whether it should be continuous or noncontinuous.
- Click the Ok button. The Date Type Properties dialog will open by default.
- Set Specific Types as desired, then Save & Close the Date Type.
Adding a new Date
- Navigate to the Calendars shortcut, then use the Add Date button to open the Add a new Date Definition dialog.
- In the dialog, select the Parent Date Type from the drop-down list, define the Date's Name, add a description (optional), and define whether the date is a workday.
- Click the Ok button. The Date Properties dialog will open by default.
- Set Specific Types as desired, then Save & Close the Date.
Copying Date Definitions
In JAMS V7.0.1678 and later, users can Copy Calendars, Date Types, and Date Definitions using the Copy To feature in JAMS.
Copy Calendars
- In the Calendars Shortcut, select the Calendar that should be copied.
- Use the Copy To button, or Right-Click and select Copy To from the drop-down list.
- In the Copy Calendar dialog that appears, set the Destination Calendar Name and Destination Server. Click on the Server field to see a drop-down list of available selections.
- With the Destination Name and Server configured as desired, click Ok.
The Calendar and all of its child Date Types and Dates will be copied over.
Copy Date Types
- In the Calendars Shortcut, select the Date Type that should be copied.
- Use the Copy To button, or Right-Click and select Copy To from the drop-down list.
- In the Copy Date Definition dialog that appears, set the Destination Calendar, Date Type Name, and Server. Click on the Server field to see a drop-down list of available selections.
- With the Destination Calendar, Name, and Server configured as desired, click Ok.
The Date Type and all of its child Dates will be copied over.
Copy Date Definitions
- In the Date List or Visual Calendar, Right-Click the Date that should be copied.
- Use the Copy To button, or Right-Click and select Copy To from the drop-down list.
- In the Copy Calendar dialog that appears, set the Destination Calendar Name and Destination Server. Click on the Server field to see a drop-down list of available selections.
- With the Destination Name and Server configured as desired, click Ok.
The Calendar and all of its child Date Types and Dates will be copied over.
Date Type References in JAMS
In JAMS V7.0.1678 and later, users can create Date Type References - a one-way relation from one Date Type to another. Date Type references are dynamic, so if dates are added to a referenced Date Type, the changes would be seen on the Date Type that contains the reference.
Date Type References are useful in any case where a date type should contain its own defined dates AND another set of predefined or separately managed dates, or multiple sets of predefined dates.
E.g. A company tracks office birthdays for each office inside of different Date Types in JAMS. Inside of a new company-wide calendar, they create a Company Birthdays Date Type. Instead of adding a date for each individual birthday to the new Company_Birthdays Date Type, they create references to the existing Japan_Office_Birthdays, US_Office_Birthdays, and UK_Office_Birthdays date types.
With the references, each office will continue to manage its individual Office's Birthdays Date Type, and any changes will automatically be reflected inside of the new Company_Birthdays Date Type where they are referenced.
↗ Japan_Office_Birthdays | |
Company_Birthdays | → US_Office_Birthdays |
↘ UK_Office_Birthdays |
Creating a Date Type Reference
For this Sample, we will create a reference to the USHolidays Date Type from "My_Sample_Date_Type".
- Navigate to the Calendars Shortcut. Note that in the screenshot below, we can see the dates for the USHolidays and My_Sample_Date_Type Date Types in the Date List and Visual Calendar.
- Right-Click on the Date Type that will reference another Date Type and select Edit.
- In the Date Type Definition dialog that appears, navigate to the Referenced Date Types tab, then click the Add... button.
- A new Date Type Search dialog will appear. Double-click the Date Type that will be referenced. Note that referenced Date Types must exist on the same JAMS Server.
- The Date Type will be added to the list of Referenced Date Types. Click Save and Close to save the changes.
- With the reference established, users will see the dates for the referenced date type whenever the Date Type that contains the reference is selected. In the image below, My_Sample_Date_type is selected and the Dates for My_Sample_Date_Type and USHolidays are visible.
With the Reference established, any changes to the dates in the USHolidays Date Type will reflect in My_Sample_Date_Type.
In this example, November 15th will be added to the USHolidays Date Type.
As soon as the new date is added to USHolidays, it can be seen from My_Sample_Date_Type, because of the reference to USHolidays.
JAMS will continue to respect configured Security on referenced Date Types. So, if a user that has full access to My_Sample_Date_Type - but only inquire access to US_Holidays - tried to edit or delete a USHolidays date from My_Sample_Date_Type, they would receive a permissions error.
It would be nice if we could add the Description column to display in the Calendar Date List control. When attempting to choose columns we are unable to see the Date Description as a selectable column using JAMS v7 Client
Is there a Powershell script method to add the Holidays dates?
Thanks a lot!
I concur with MaryAnn, This would be great :).
Hello, there is a sample job in the Samples folder that comes installed with JAMS called "AddHolidays" that shows how you can programmatically add dates to a Date Type.