Setting up calendars for the planning board

In this guide, you will:

• Create a hierarchy of calendars
• Assign resources to calendars
• Apply calendars on the planning board

This is a deep dive of the calendars on the planning board. There is more to it than that because calendars are also used in the Gantt chart. To maintain a narrow focus, we won't pay any attention to the Gantt chart in this guide. However, it is enough to know that calendars in the Gantt chart behave similarly and that the integration with the planning board - if set up correctly - appears to be seamless.

Even though the tutorial is very simple and does not reflect real-life situations, it should get the message across that calendars can be used to optimize the resource planning. It is not a cutting edge technology by any means but due its simplicity and integration with the core of the application, it is potentially very powerful so it's worth to spend some time learning this feature.

Permissions

Before we get cracking on the calendar setup, let's check if your user has the right permission set. You need an augmented authorization level to access most of the administration and setting views:

• To access the settings modules, you need to be assigned to a role which contains the 'Settings Module' user action.
• The 'Administration Module' is the user action you need for the views in the administration area.

Administrators can easily assign a role to you but you have to log out and log in again to see the changes.

Creating calendars

Calendars navigation

If you have the right permissions, you will be able to navigate to the 'Calendars' view from the sidebar navigation menu:

.

Alternatively, you can navigate to the relative URI Settings/Calendars.

Create a calendar hierarchy

The calendar setup screen is divided into two areas:

• The tree list with calendars on the left
• The selected calendar's details, business hours and overrides

The information displayed in the main panel hinges on the selected item in the tree. Below is how a default calendar looks like in the setup screen ¹:

After this tutorial, we will have a setup like this:

.
+-- Base calendar 2019
|   +-- Business hours
|        +-- 08:00 - 12:00
|        +-- 13:00 - 15:00
|        +-- 15:15 - 17:30
|   +-- Holidays
|       +-- December 25th
|   +-- Modified schedule
|       +-- December 24th (partially working)
|       +-- Every Tuesday between December 16th and December 22th:
|           +-- 08:00 - 12:00
|           +-- 12:30 - 19:00
|       +-- Every Friday
|           +-- 09:00 - 14:00
|   +-- Child calendars
|           +-- Workers 2019
|               +-- Holidays
|                   +-- Week of the July 15th
|           +-- Clerks 2019
|               +-- Holidays
|                   +-- December 24th
+-- Default calendar
|   +-- Business hours
|        +-- 08:00 - 16:00

Add a calendar

The time has come to start the calendar wizardry. We will add three calendars: one base calendar that will be used by two other calendars. Nested calendars are useful to manage common schedules across teams. It also reduces data duplication to a bare minimum. It is not required to have nested calendars but it is certainly recommended when you have many resources to manage.

To add a new calendar, simply click the "Add" button. A new line will be added and the center panel will focus on the new calendar. We'll start with the base calendar by giving it a code (a unique value which can serve as a reference in back-office systems) and a descriptive name.

Be aware that these form fields are not saved automatically, as the red circling sync icon shows in the tree. This moving icon warns there are pending changes. Click on this button to save the calendar's master data, which consists of the form fields (code, name, default, etc.) and the first tab in the panel below (the settings tab). If you were to refresh the page, you'd notice the record has been persisted.

Setting the business hours

Now let's change the business hours, which by default is set to 08:00 - 16:00. Navigate to the corresponding tab, which contains a grid that allows you to add, update and remove business hours. Business hours are sets of working hours which, put together, compose a working day. Most people don't work eight hours straight, most of them have some kind of lunch break. If you want to update an existing set, simply double click on the cell (either start or end), which reveals a selection list:

You can create as many sets as you desire:

The only caveat is that business hours should not overlap. For example, 08:00 - 12:00 and 11:30 - 13:30 is an invalid setup and will cause problems in the system. Also note that changes are persisted immediately, so there is no need to synchronize the calendar manually.

Adding a day override

Let's add some holidays to the base calendar that apply to all the members of the organization. Holidays like Christmas were almost designed to be put in a base calendar. Navigate to the "Day overrides" tab, which is empty by default. For this grid to work, we will need to work with the date picker, in the area above the tab panel.

In the date picker, navigate to December and select the 25th. You will notice the selected day will be marked in a different color. Press the "Add" button in the day overrides grid and notice how a new record is appended to the grid with the date pre-populated:

This transaction is persisted as a full non-working day. By editing the cells in the grid, the name and/or the date can easily be modified:

Let's add another day override on Christmas Eve, when people are allowed to leave the office at 15:00. This is different than Christmas because people have to work but not the entire day, so we will have to do some extra work. After having added a record in the day overrides grid, make sure it is selected and click the "Edit" button. This reveals a window where you can indicate whether this is a working day or a non-working day. If you select the working time option, you have to specify the working hours for this particular day. These hours can be anything and will override the default business hours for this day only.

Just like the previous section, date conflicts are problematic so make sure not to have two day overrides on the same day. Click 'OK' to save the changes. There is no need to synchronize the calendar, changes are automatically saved.

Adding a week override

A week override is a range of week days for a limited time range. Long holidays or temporary altered work schedules make a good case for a week override. Just like a day override, select a start date in the date picker and click "Add" in the week overrides grid. Notice how an overridden week is visualized in the date picker:

At this point we should point out that - unlike the other grids - this particular transaction is not saved. You must configure at least one day in the "Edit" dialog to save this override. After that, changes will be saved automatically. This is to avoid empty overrides which would cause confusion and undesirable results.

In addition to the two familiar options - working and non-working hours - a third option exists: the default time. This option will inherit the settings for the calendar for this particular day during this overridden week. In this example, if you select Monday to use the default settings, Monday 16 December will be a normal business day. In contrast, Tuesday 17 December is slightly different because a week override indicates a different working days on Tuesday between 16 December and 22 December.

You can always consult the date picker and click on a colored cell, which will reveal more details about that particular override:

Working hours for Dec 16, 2019:
15:15-17:30
13:00-15:00
08:00-12:00
Based on: override "[Without name]: 2019-12-16 - 2019-12-22" in calendar "Base calendar 2019"
----
Working hours for Dec 17, 2019:
08:00-12:00
12:30-19:00
Based on: override "[Without name]: 2019-12-16 - 2019-12-22" in calendar "Base calendar 2019"

Adding a week day

The last override option is a fairly simple one: week day overrides are perpetual overrides for a given week day. For example, every Friday afternoon people can leave the office at 15:00 instead of 16:00. Like the day overrides, you can specify whether this day is working or non-working. As opposed to the other two override types, week days are not visualized in the date picker but they are applied in the recalculation algorithms.

Calendar inheritance

So far we've created a base calendar for 2019 with a few overrides. Even though this calendar can be used, we want to make two more 'specialized' calendars: one for workers and one for clerks. Let's assume all workers need to take some time off in July to escape the heat where the clerks get some extra time off at the end of the year.

To do this, we have to add two new calendars: 'Workers 2019' and 'Clerks 2019'. Besides the code and the name, we will also select a parent calendar: the base calendar 2019. Don't forget to save the calendars. Changes made to all the calendars will be saved in one transaction so there is no need to process them one by one. This should be the result in the calendar tree:

Both calendars will inherit the settings from the base calendar. In other words, unless you override something on a lower level (i.e. the workers or clerks calendar) the settings from the higher levels (i.e. the base calendar) will be used. In this case, all workers and clerks will have to work less on Christmas Eve and get the day off on Christmas day. Settings from a higher level - the parent calendars - are not displayed in the date picker of the inherited calendars - the child calendars, so be aware of the hierarchy in the tree.

Let's navigate to Christmas Eve for the clerks calendar, which is marked as a shorter working day by the parent calendar. Override this day and mark it as non-working (no action is required as this is the default value). Next, select the workers calendar, add a week override in July 2019 and flag all days as non-working.

Splendid! We're almost ready to see the two calendars in action. Before we can pop over to the planning board, we need to assign these calendars to some resources.

Assigning resources to calendars

Resource calendars navigation

Another setup screen involves the assignment of calendars to resources (or vice versa). The resource calendar assignment screen is accessible via the sidebar navigation menu:

.

Alternatively, you can navigate to the relative URI Settings/ResourceCalendars.

Calendar assignment

By default, all resources are subjected to the default calendar. However, administrators can assign a calendar to a resource for a particular time range. The process is quite straightforward: you choose a resource, pick a calendar and determine when and how long you want this calendar to apply.

A line in the grid can be construed as follows: 'this calendar will be applied to this resource between this date and that date'. A resource, therefore, is not limited to one calendar. A calendar assignment is limited in time, which allows for very detailed and flexible work schedules. For instance, think about all those people who work in shifts.

For the sake of this guide, locate two resources that appear close to each other on your planning board. This way, the different calendars will be easier to see in the planning board later. There is only one final step we have to do before we can start using the calendars in the planning board.

Configuring the application

Application navigation

If you are authorized to access the administration module, navigate to the application setup:

Alternatively, you can navigate to the relative URI Administration/Application.

Configuring calendars for the planning board

In this view, navigate to the "Planning" tab. There are three fields we are interested in:

• Visualize resource calendars
• Resource zone color
• Switch on calendar mode

The first two options are related to the visualization of the calendars in the planning board. The third option refers to the inclusion of calendars to determine the duration of appointments. For the sake of this guide, enable both flags and select a spunky color from the color picker.

Let's fire up the planning view.

Working with the planning board

Visualizing calendars

Go to the planning board and navigate to the resources you configured in the resource calendars setup. Then, use the date picker component to navigate to the 2019 Christmas period. If all went well, you should see how the two resources have quite different shaded time slots. This is the result of the calendars!

The shaded areas represent the resources' unavailable times , which leaves the empty areas to be the working times. From this example you can clearly see that Wylma Charlet is a clerk because she doesn't have to work on Christmas Eve. Willy McReynolds does have to work, so he would be a worker. Further down the list, you will encounter resources with the default calendar: Burch Mougel has a work schedule according to the settings of the default calendar.

Working with appointments

Our current setup has the calendar mode switched on. If it wasn't turned on, everything in this and the next section would not be applicable. The unavailable times can still be shown but they are not necessarily enforced.

Switch to the day view and locate Christmas Eve on the the planning board:

Select the 11:00 time slot, right click and press the "New" button. The editor will be revealed, make sure not to disable to calendar mode button. It is enabled by default so keep it that way.

Nothing specially has happened so far, but this is about to change if you drag this appointment slightly to the right, like so:

This is the result after the appointment is dropped:

Notice how the total duration is different from the working time? This makes sense because there is a 30 minute break between 12:30 and 13:00. The task requires one hour to complete, so it would be incorrect to keep the duration of the appointment to an hour since the resource is unavailable for half an hour. This is why Dime.Scheduler looks at the calendars that apply, and extend the duration of the appointment until the working time can be completed.

If you do the same for the other resource, you'll see a more radical change:

The first available time slot is not for another two days so the appointment's duration will be extended until the task can be completed. In this case the appointment lasts 45 hours for a task which takes only one hour. Of course, this kind of planning is complete madness, but you get the point.

Resolving the leading resource

Looking at the image above, you may wonder what would happen if an appointment has two or more resources assigned, and which calendar would be used in case the resources have a different schedule. We refer to this issue as the resource calendar constraint resolution and you can see it in action as soon as you add a second resource to an appointment. You can use the SHIFT + drag combination to add a resource to the appointment. Before you drop the appointment, the resolution window will be prompted:

This window lets you choose what we call the 'leading resource'. The leading resource is the resource that will be used as the source for calculating the duration of the appointment. In other words, this resource's calendars (if any) will be applied.

The result of the recalculation will be correct for the leading resource but this won't necessarily be true for the other resources. This constraint resolution window will be prompted every time you modify the appointment. This gives you the chance to choose the most relevant resource.

If this is annoying, you can always switch off calendar modes on three levels: globally, planning board or appointment. For the latter, there are three ways to toggle the calendar mode:

• Via the constraint resolution window:

  

• Via the context menu:

  

• Via the editor:

  

As long as the calendar mode is switched off, the appointment will ignore the calendars and act as if there are no calendars. However, the instant you switch it on again, you will be requested to choose a leading resource.

The settings on the appointments are (temporarily) ignored if the calendar mode is switched off on the planning board ². If the calendar mode is switched off entirely, the buttons won't even be available. As we've explained here, it is a cascading setting which allows for ultimate flexibility.

Summary

This guide started by creating a calendar hierarchy. In this hierarchy, common calendar settings and holidays were inherited by clear-cut calendars which reflect the way organizations work. Then we assigned some resources that had to be subjected to these calendars. We subsequently configured the application and finally we created some appointments to see the effects of calendars on the planning board.

Read more

• Planning board
• Calendar-based appointment duration recalculation
• Calendars
• Role-based access control
• Roles

Footnotes

1. There must be a default calendar, at all times. Changes resulting in a calendar setup without a default calendar will be rejected until this constraint is complied with. ↩

2. This can lead to some interesting situations when you have the same appointment in the view of multiple planning boards (of which one has switched off the calendar mode) in your user profile. ↩