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

# Architecture and Data Flow

> Nextedy GANTT is a Polarion server extension that embeds an interactive Gantt chart directly into Polarion LiveDoc and Wiki pages.

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

## Two-Tier Architecture

The Gantt chart operates as a client-server system within Polarion. The **server tier** is a Java plugin that runs inside the Polarion application server. It handles data retrieval, field mapping, calendar resolution, and persistence. The **client tier** is a JavaScript application that renders the interactive chart in the browser, manages user interactions (drag, resize, lightbox editing), and communicates changes back to the server.

Think of it like a spreadsheet application: the server is the database that stores and validates data, while the client is the visual interface where you interact with it.

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

## Data Loading Sequence

When a Polarion page containing a Gantt chart loads, the following sequence occurs:

1. **Initialization** -- The server reads chart parameters (data source, field mappings, calendar settings) and resolves the configuration into a typed configuration object
2. **Data retrieval** -- The server queries Polarion for work items matching the configured dataset, resolves parent-child relationships using the configured `parentRoles`, and builds dependency links from `dependsRoles`
3. **Task conversion** -- Each work item is converted into a task object with properties like `start_date`, `end_date`, `duration`, `progress`, `parent`, and `type`. Custom fields listed in the field filter are included as additional fields
4. **Calendar resolution** -- If working calendars are enabled (`wCal_GLOBAL`), the server computes working hours per day for each resource, including user calendars and team assignments
5. **JSON serialization** -- The complete dataset (tasks, links, resource collections, and load statistics) is serialized to JSON and sent to the client
6. **Client rendering** -- The JavaScript application parses the JSON, applies the configuration, and renders the Gantt chart with its grid, timeline, and optional resource view

## The Data Payload

The server returns a structured JSON payload containing four key sections:

| Section         | Content                               | Purpose                                                          |
| --------------- | ------------------------------------- | ---------------------------------------------------------------- |
| `data`          | Array of task objects                 | Work items or plan items to display as task bars                 |
| `links`         | Array of link objects                 | Dependency relationships (FS, SS, FF, SF) between tasks          |
| `collections`   | Map with `resources` and `loadInfo`   | Resource definitions and capacity metadata for the resource view |
| Load statistics | Item counts, errors, server load time | Footer status bar showing what was loaded and any issues         |

The load statistics track how many items were loaded, skipped (due to limits), filtered, hidden, or unresolvable. When tasks reference work items that cannot be accessed (due to permissions or deletion), they appear as unresolvable items in the error count.

## Configuration Flow

Configuration reaches the Gantt through two channels, each with a different scope:

* **Per-instance parameters** are set on each Gantt chart through the Polarion page editor. They control data source, field mappings, visual options, and feature toggles for that specific chart. Examples: `Start Field`, `End Field`, `Parent Role`, `Show Resource View`.
* **Administration properties** are set globally via Polarion Configuration Properties (`nextedy.gantt.*`). They control system-wide behavior like auto-scheduling defaults, calendar project references, and license caching. Examples: `nextedy.gantt.default.auto_scheduling`, `nextedy.gantt.workitemCalendar.projectId`.

For more on how these two layers interact, see [Configuration Layers and Precedence](/gantt/concepts/configuration-hierarchy).

<Tip title="Per-instance parameters take precedence">
  When the same setting is available at both levels (such as the today's date override), the per-instance parameter value takes precedence over the administration property.
</Tip>

## Persistence Model

Gantt uses an optimistic persistence model. When you drag a task bar, resize it, or edit fields in the lightbox, the changes are staged locally in the browser. A modified indicator appears on affected tasks. Changes are only written back to Polarion when you click **Save** in the toolbar.

The save operation sends each modified task to the server, which updates the corresponding Polarion work item fields: `startField`, `endField`, `durationField`, `progressField`, `resourceField`, and any custom fields from the field filter. Dependency link changes (add or remove) update Polarion work item link roles.

<Warning title="Concurrent editing">
  The Gantt uses a last-save-wins model. If two users edit the same work item simultaneously, the last save overwrites the previous one. There is no built-in conflict detection for concurrent edits.
</Warning>

## Scripting Extension Points

Gantt provides server-side scripting hooks for customization:

* **Item Script** -- A server-side JavaScript snippet that executes for each work item during data loading. The script receives the source work item object and the task object being built, allowing you to read additional fields and pass custom data to the client. This is commonly used for custom color logic, computed labels, or baseline date injection.
* **Page Script** -- A server-side **Apache Velocity** template that executes once during page rendering, with access to the Gantt configuration and the Polarion page context (projects, users, plans, work items). Its rendered output is embedded into the widget as JavaScript. Used for dynamic configuration adjustments.

The Item Script runs in a server-side JavaScript environment and the Page Script as a server-side Velocity template -- both prepare data before it reaches the client, not in the browser. A client-side **Gantt Config Script** and a server-side **Markers Script** are also available (see the scripting reference).

## Related Topics

* [Product Overview](/gantt/concepts/overview) -- High-level introduction to Gantt capabilities and use cases
* [Data Mapping and Field Resolution](/gantt/concepts/data-mapping) -- How work item fields connect to Gantt scheduling properties
* [Working Calendars and Scheduling](/gantt/concepts/working-calendars) -- How calendar data is resolved and sent to the client
* [Item Color Logic -- Static, Dynamic, and Progress Colors](/gantt/concepts/item-color-logic) -- How Item Script customizes task appearance

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