> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working Calendars and Scheduling

> Nextedy GANTT supports working calendars that define which days and hours count as working time.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Why Working Calendars Matter

Consider a task estimated at 5 working days starting on a Thursday. Without a working calendar, the Gantt schedules it to end on Monday (5 calendar days later, including the weekend). With a working calendar that defines a standard Monday-Friday work week, the Gantt skips Saturday and Sunday, correctly scheduling the task to end on the following Wednesday.

Working calendars also affect the resource view. When a user is on vacation, their calendar marks those days as non-working, and the resource view reflects zero available capacity for that period. This prevents the Gantt from showing misleading workload data.

## Three-Level Calendar Cascade

The Gantt resolves working calendars through a three-level cascade, where each level adds specificity:

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/DDjWgCW2DWY5biNv/gantt/diagrams/concepts/working-calendars/diagram-1.svg?fit=max&auto=format&n=DDjWgCW2DWY5biNv&q=85&s=3f057061ad199ff1be61ed23c561592a" alt="diagram" style={{ maxWidth: "400px", width: "100%" }} width="400" height="320" data-path="gantt/diagrams/concepts/working-calendars/diagram-1.svg" />
</Frame>

1. **Global calendar** -- The base calendar defining standard working hours for the organization (typically Monday-Friday, 8 hours per day). Enabled via the `Use Working Calendar` (`wCal_GLOBAL`) parameter.
2. **User calendars** -- Per-user overrides loaded from Polarion calendar work items. Each user can have different working days, hours, and exceptions. Enabled via `Load User Calendars` (`wCal_USER`), which depends on `Use Working Calendar` being active.
3. **Team assignments** -- Capacity percentages from team assignment work items that further reduce a user's effective availability. Enabled via `Load Team Assignments` (`wCal_ASSIGNMENTS`), which depends on `Load User Calendars` being active.

These three levels are progressively enabled -- each subsequent level requires the previous one to be active first.

<Tip title="Progressive parameter disclosure">
  In the widget parameter editor, the `Load User Calendars` option only appears after `Use Working Calendar` is enabled. Similarly, `Load Team Assignments` only appears after `Load User Calendars` is enabled. This cascading visibility prevents configuration errors.
</Tip>

## Calendar Work Item Types

Working calendars are defined using four Polarion work item types in a dedicated calendar project:

| Work item type | Purpose                                   | Effect                                                            |
| -------------- | ----------------------------------------- | ----------------------------------------------------------------- |
| **Calendar**   | Defines regular working hours per weekday | Sets the base schedule (e.g., Mon 08:00-16:00)                    |
| **Time Off**   | Marks date ranges as non-working          | Removes days from scheduling (holidays, vacations)                |
| **Time On**    | Overrides Time Off for specific users     | Adds working days back (e.g., user works during a public holiday) |
| **Tweak**      | Adjusts working hours for a date range    | Changes daily hours without changing working/non-working status   |

### Calendar Inheritance

A user calendar can inherit base hours from a global calendar via the `inherits from` work item link role. The user calendar then only needs to specify the days that differ from the global schedule. For example, if the global calendar defines 8-hour workdays Monday through Friday, a user calendar that inherits from it only needs to specify that Wednesdays are off for that user.

The resolution order for each day is: base (inherited) calendar > regular weekday hours > tweaks > exceptions (Time Off / Time On). This means Time On overrides Time Off, and tweaks adjust hours within an already-working day.

### Weekday Hour Format

Each calendar work item has seven weekday fields (Monday through Sunday). The format is `HH:mm,HH:mm` to specify work start and end times. Use `-` to mark a day as explicitly non-working. Leave the field empty to inherit from the parent calendar.

## Connecting Calendars to Projects

Working calendars live in a dedicated Polarion project. To connect this calendar project to a scheduling project, two administration properties must be set:

* `nextedy.gantt.workitemCalendar.projectId` -- The project ID of the calendar project
* `nextedy.gantt.workitemCalendar.globalID` -- The work item ID of the calendar that serves as the global (company-wide) calendar

<Warning title="Both projects need the configuration">
  These properties must be set in both the calendar project and every project that uses the calendar. Missing this configuration is a common setup issue.
</Warning>

## Calendar Caching and Performance

The `Previous Years to Load` and `Next Years to Load` parameters control how many years of calendar data are pre-computed. More years means more working-day data is available for long-range views, but at the cost of increased startup time and memory usage. For most use cases, 1-2 years in each direction is sufficient.

The `Cache Working Calendars` (`UseCache`) parameter enables server-side caching of computed calendar data. When enabled, repeated Gantt loads reuse cached data instead of recomputing calendars from work items. After making changes to calendar work items, the cache must be cleared using the **Clear Calendar Cache** toolbar button or the `api/clearCalendarCache` endpoint.

<Info title="Calendar holder">
  The administration property `nextedy.gantt.calendarHolder` specifies a Polarion user ID whose calendar work item is used as the global working calendar. This is an alternative to `workitemCalendar.globalID` for organization-wide calendar configuration.
</Info>

## How Calendars Affect the Gantt

When calendars are enabled, several Gantt behaviors change:

* **Duration calculations** skip non-working days -- a 5-day task avoids weekends and holidays
* **Off-day cell highlighting** marks non-working days with a visual background in the timeline
* **Resource view cells** show grey for unavailable days
* **Auto-scheduling** respects calendar boundaries when propagating dates
* **Resource load calculations** use actual available hours per user instead of a flat 8 hours

Users without a Polarion calendar get a zero-capacity calendar, showing no available hours in workload calculations. Ensure every resource in the Gantt has either a personal calendar or inherits from the global calendar.

## Related Topics

* [Resource Load Calculation Modes](/gantt/concepts/resource-load-modes) -- How calendars influence workload calculations
* [Capacity Modifiers and Team Capacity](/gantt/concepts/capacity-modifiers) -- How team assignments layer on top of calendars
* [Auto-Scheduling and Dependency Propagation](/gantt/concepts/auto-scheduling) -- How calendars affect dependency-driven scheduling

<LastReviewed date="2026-07-07" />