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

# Config Script API

> The Config Script API exposes the runtime configuration object that controls how the Nextedy PLANNINGBOARD renders and behaves.

## Overview

```text theme={null}
Planningboard initialisation
        |
        v
+----------------------------+
|   Widget Parameters        |  (per-instance, set in Polarion page editor)
+----------------------------+
        |
        v
+----------------------------+
|   Config Script            |  (JavaScript — runs server-side or client-side)
|   receives config object   |  ← Config Script API described on this page
+----------------------------+
        |
        v
+----------------------------+
|   Board renders            |
|   (swimlanes, cards,       |
|    capacity bars)          |
+----------------------------+
```

The config object is the single place where tooltip templates, custom data per Plan column, and scheduler view settings are applied programmatically. Changes made inside the config script take effect on the next render; call `setCurrentView()` to force an immediate re-render after modifying the config at runtime.

***

## Capacity Tooltip Properties

These properties control how capacity information is presented in the tooltip that appears when hovering over a Plan column's capacity bar.

| Property                | Type                 | Default     | Description                                                                                                                                                                                                                     |
| ----------------------- | -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columnTooltipTemplate` | `string \| function` | `undefined` | Custom template for the capacity tooltip on Plan columns. When a string, treated as a template. When a function, receives `column` and `row` objects and must return an HTML string. When not set, the default tooltip is used. |

### Default Tooltip

When `columnTooltipTemplate` is not configured, the board displays an aggregate capacity tooltip showing:

* **Capacity** — total capacity for the Plan column
* **Done** — effort marked as done
* **Todo** — remaining effort
* **Available** — capacity minus allocated effort

### Custom Tooltip Function

When `columnTooltipTemplate` is a function, it receives the current column and row context objects:

```javascript theme={null}
config.columnTooltipTemplate = function(column, row) {
  // column and row objects provide plan and resource data
  // Must return an HTML string
  return "<div>Custom tooltip content</div>";
};
```

<Tip title="Per-user allocation breakdown">
  A function-based `columnTooltipTemplate` enables per-user capacity breakdowns showing Available / Allocated / Total for each team member. Overallocated users (negative available capacity) should be highlighted — for example, by wrapping negative values in a `<span style={{color: "red"}}>` element.
</Tip>

<Warning title="Overallocation display">
  When a user's available capacity is negative (overallocated), the board renders the value in red by default in the built-in tooltip. Replicate this behaviour in custom templates by checking for negative values and applying appropriate styling.
</Warning>

***

## Plan Column Data Properties

These properties attach custom data to individual Plan columns, making it available inside tooltip templates and other rendering callbacks.

| Property     | Type     | Default     | Description                                                                                                                                                                           |
| ------------ | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scriptData` | `object` | `undefined` | Arbitrary custom data stored per Plan in the scheduler config. Values set here are accessible inside `columnTooltipTemplate` and other scripting callbacks. Keyed by plan identifier. |

### Example: Storing custom data per Plan

```javascript theme={null}
// Attach custom data to a plan column identified by its ID
config.scriptData = {
  "iteration-1": { team: "Backend", budget: 80 },
  "iteration-2": { team: "Frontend", budget: 60 }
};
```

This data can then be read inside a `columnTooltipTemplate` function to render plan-specific information.

***

## Scheduler View Control

| Method             | Signature                | Description                                                                                                                                                |
| ------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setCurrentView()` | `setCurrentView(): void` | Refreshes the scheduler view. Call after programmatically modifying `columnTooltipTemplate` or other view configuration properties to trigger a re-render. |

<Note title="When to call setCurrentView">
  `setCurrentView()` is required whenever configuration properties are changed at runtime — for example, after updating `columnTooltipTemplate` in response to a user action. Changes made during the initial config script execution (before first render) do not require an explicit call.
</Note>

***

## Configuration Example

The following example demonstrates a config script that adds a per-user capacity breakdown tooltip to all Plan columns.

```javascript theme={null}
// Custom capacity tooltip showing per-user allocation
config.columnTooltipTemplate = function(column, row) {
  var html = '<div class="capacity-breakdown">';
  html += '<strong>' + column.label + '</strong><br/>';

  // scriptData can carry plan-specific data set elsewhere in the config
  var planData = config.scriptData && config.scriptData[column.id];
  if (planData && planData.users) {
    planData.users.forEach(function(user) {
      var available = user.total - user.allocated;
      var color = available < 0 ? 'red' : 'inherit';
      html += '<div>' + user.name + ': ';
      html += '<span style="color:' + color + '">' + available + '</span>';
      html += ' / ' + user.allocated + ' / ' + user.total;
      html += '</div>';
    });
  }

  html += '</div>';
  return html;
};

// Attach per-plan user data
config.scriptData = {
  "sprint-1": {
    users: [
      { name: "Alice", allocated: 40, total: 40 },
      { name: "Bob",   allocated: 50, total: 40 }  // overallocated
    ]
  }
};

// Force re-render to apply the new template
setCurrentView();
```

***

## REST API Integration

The Config Script API operates on the client-side configuration layer. The underlying data served to the board is provided by the REST API described on the [REST API](/planningboard/reference/api/rest-api) page. Key data endpoints relevant to capacity configuration:

| Endpoint    | Method | Purpose                                                                                                                                               |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/data` | `GET`  | Retrieves Planningboard data (tasks, items) in JSON format. Date format: `dd-MM-yyyy HH:mm`.                                                          |
| `/capacity` | `POST` | Sets the capacity value for a specific Plan in a project. Request body requires `project`, `plan` (format: `planId/planName`), and `capacity` fields. |

These endpoints feed the data that capacity tooltip templates present. Customising the tooltip via `columnTooltipTemplate` does not change the underlying data — it only changes how that data is displayed.

***

## Limitations

<Info title="Verify in application">
  The Config Script API surface documented here is based on confirmed source context (tooltip template and `scriptData` customisation, `setCurrentView` method). Additional scheduler configuration properties may be available in the running product. Consult the [Scripting Properties](/planningboard/reference/configuration-properties/scripting-properties) reference for administration-level scripting configuration options.
</Info>

* **Multi-assignee capacity**: the capacity model does not support multi-assignee effort distribution. Per-user capacity breakdowns in custom tooltips reflect single-assignee allocation only.
* **Sub-item effort**: effort is not automatically distributed from parent items to sub-items. Tooltip data reflects top-level item estimates.
* **Whitespace sensitivity**: capacity-related configuration properties are whitespace-sensitive. Avoid leading or trailing spaces in property values passed to the config object.

***

## Related Pages

* [Scripting API](/planningboard/reference/api/scripting-api) — entry points and execution context for config scripts
* [Item Script API](/planningboard/reference/api/item-script-api) — API available when scripting individual card rendering
* [Data Script API](/planningboard/reference/api/data-script-api) — API for customising the data query and transformation layer
* [REST API](/planningboard/reference/api/rest-api) — HTTP endpoints for data retrieval and capacity updates
* [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) — widget parameters controlling capacity display
* [Scripting Properties](/planningboard/reference/configuration-properties/scripting-properties) — administration properties for enabling and configuring scripting

<Accordion title="Sources">
  **KB Articles**

  * Planningboard: Customizable Statistics and Capacity Indicators
  * Planningboard Widget Parameters

  **Source Code**

  * `PlanningBoardApiServlet.java`
  * `capacityTooltipRendering.cy.ts`
  * `PlanningBoardViewServlet.java`
  * `PlanningBoardWidget.java`
</Accordion>