> ## 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.

# Configuration Layers and Precedence

> Nextedy GANTT uses a layered configuration system where settings can be defined at multiple levels.

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>;
};

## Three Layers of Configuration

Think of the configuration hierarchy like CSS specificity -- the most specific setting wins. Gantt resolves every configurable property by checking three layers in order:

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

### Layer 1: Built-in Defaults

Every configurable property has a hardcoded default value. These defaults provide a working Gantt chart out of the box without any configuration. Key defaults include:

| Property          | Default Value    |
| ----------------- | ---------------- |
| Default scale     | `W` (Week view)  |
| Progress coloring | `true`           |
| Drag children     | `true`           |
| Show today marker | `true`           |
| Max items         | `100`            |
| Start field       | `gantt_start`    |
| Duration field    | `gantt_duration` |
| Progress field    | `gantt_progress` |
| Show unplanned    | `true`           |
| Undo steps        | `10`             |

### Layer 2: Administration Properties

Administrators can override defaults system-wide or per-project by setting **Configuration Properties** in Polarion's administration console (**Administration > Configuration Properties**). These properties follow a naming convention:

* **General properties** -- `nextedy.gantt.<property>` applies globally regardless of Gantt mode.
* **Work Items Gantt defaults** -- `nextedy.gantt.workitems.default.<property>` sets defaults for Work Items Gantt instances.
* **Plans Gantt defaults** -- `nextedy.gantt.plans.default.<property>` sets defaults for Plans Gantt instances.

For example, to make auto-scheduling default to enabled across all Work Items Gantt instances in a project:

```
nextedy.gantt.default.auto_scheduling=true
```

Or to change the default scale for all Work Items Gantt instances:

```
nextedy.gantt.workitems.default.scale=M
```

<Note title="When Administration Defaults Apply">
  Administration property defaults are used as the **initial value** when you add a new Gantt chart to a page. Once the chart is placed, its own parameter values take precedence. Changing an administration default does not retroactively update existing charts that already have explicit values set.
</Note>

### Layer 3: Per-Instance Parameters

Per-instance parameters are set directly on each Gantt chart through the Polarion wiki page editor. They represent the most specific level of configuration and always take precedence when set.

These parameters are organized into sections in the configuration panel:

* **Data set** -- which work items or plans to display
* **Data Mapping** -- field mappings for start, end, duration, progress
* **Work Item Types** -- presentation modes, parent rules, create-new settings
* **Resource View** -- resource field, load mode, allocation colors
* **Working Calendars** -- global calendar, user calendars, team assignments
* **Advanced** -- scripts, read-only mode, always-edit, toolbar visibility

## Properties That Only Exist at One Level

Some configuration properties exist only as administration properties and cannot be set per instance:

| Property                                             | Scope      | Purpose                                        |
| ---------------------------------------------------- | ---------- | ---------------------------------------------- |
| `nextedy.gantt.default.auto_scheduling`              | Admin only | Toggle auto-scheduling default                 |
| `nextedy.gantt.default.critical_path`                | Admin only | Toggle critical path visualization default     |
| `nextedy.gantt.workitems.default.forward_dependency` | Admin only | Reverse dependency direction                   |
| `nextedy.gantt.workitems.default_duration`           | Admin only | Default task duration in days (default: 10)    |
| `nextedy.gantt.workitems.default.link_lag`           | Admin only | Default dependency link lag (default: 0)       |
| `nextedy.gantt.workitems.resolved_readonly`          | Admin only | Prevent editing resolved items (default: true) |
| `nextedy.gantt.teamManagementProjectId`              | Admin only | External team management project               |
| `nextedy.gantt.workitemCalendar.projectId`           | Admin only | Work item calendar project                     |

Conversely, certain settings are only available as per-instance parameters because they are inherently instance-specific (e.g., the data set query, scripts, sidebar fields).

## Progressive Disclosure in the Configuration Panel

The parameter editor uses progressive disclosure to reduce complexity. Sub-parameters are only visible when their parent feature is enabled:

* **Load User Calendars** appears only when **Use Working Calendar** is enabled
* **Load Team Assignments** appears only when **Load User Calendars** is enabled
* **Deadline Field** and **Passed Deadline Color** appear only when **Show Deadlines** is enabled
* **Compare to date** appears only when **Show Baselines** is enabled

This cascading visibility means you will not see advanced options until you enable the features they belong to.

## Gantt Config Script and Item Script

Beyond the structured parameter system, Gantt provides scripting hooks for advanced customization. The two that interact with configuration are:

* **Gantt Config Script** -- client-side JavaScript executed once during chart initialization. Configures global chart behavior (colors, working hours, scale settings).
* **Item Script** -- server-side JavaScript executed for each work item during data loading. Customizes individual task properties (colors, dates, read-only flags).

(A server-side **Markers Script** and a **Page Script** are also available -- see [Architecture and Data Flow](/gantt/concepts/architecture) and the scripting reference.)

Scripts provide the most flexibility but bypass the standard configuration validation. They execute in addition to -- not instead of -- the configuration hierarchy.

<Accordion title="Read-Only Mode Has Three Sources">
  A Gantt chart can become read-only from three different sources: (1) the `readonly` parameter is set to true, (2) the current user is not licensed, or (3) a Polarion baseline snapshot is active. All three conditions are checked independently and any one will trigger read-only mode.
</Accordion>

## Related Pages

* [Architecture and Data Flow](/gantt/concepts/architecture) -- how configuration flows from server to client
* [User Settings and Local Storage Persistence](/gantt/concepts/user-settings-persistence) -- how per-user preferences layer on top
* [Data Mapping and Field Resolution](/gantt/concepts/data-mapping) -- the field mapping subset of configuration

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