Config Script API

Overview

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.

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.

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

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

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

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.

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.

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

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

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.

Configuration Example

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

// 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 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

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 reference for administration-level scripting configuration options.

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.

Scripting API — entry points and execution context for config scripts
Item Script API — API available when scripting individual card rendering
Data Script API — API for customising the data query and transformation layer
REST API — HTTP endpoints for data retrieval and capacity updates
Capacity Parameters — widget parameters controlling capacity display
Scripting Properties — administration properties for enabling and configuring scripting

Sources

KB Articles

Planningboard: Customizable Statistics and Capacity Indicators
Planningboard Widget Parameters

Source Code

PlanningBoardApiServlet.java
capacityTooltipRendering.cy.ts
PlanningBoardViewServlet.java
PlanningBoardWidget.java

Overview

Capacity Tooltip Properties

Default Tooltip

Custom Tooltip Function

Plan Column Data Properties

Example: Storing custom data per Plan

Scheduler View Control

Configuration Example

REST API Integration

Limitations

​Overview

​Capacity Tooltip Properties

​Default Tooltip

​Custom Tooltip Function

​Plan Column Data Properties

​Example: Storing custom data per Plan

​Scheduler View Control

​Configuration Example

​REST API Integration

​Limitations

​Related Pages

Overview

Capacity Tooltip Properties

Default Tooltip

Custom Tooltip Function

Plan Column Data Properties

Example: Storing custom data per Plan

Scheduler View Control

Configuration Example

REST API Integration

Limitations

Related Pages