Config Scripts

What is a config script?

A config script is a JavaScript snippet you supply via the advScript widget parameter. The script runs in the Planningboard widget context and has access to the board configuration object before the board renders. This allows you to manipulate configuration values that are not exposed directly in the widget parameter editor, or to set them conditionally based on runtime context.

Config scripts execute client-side, in the Planningboard widget frame. They are not server-side scripts. Changes you make affect the current board session only — they do not persist to the widget parameter store.

When to use config scripts

Config scripts are suited for:

Overriding a configuration property that cannot be set through the standard widget parameters UI
Applying conditional logic (for example: show different capacity settings for different teams)
Injecting dynamic values that depend on page context or URL parameters

For most configuration tasks, use the Widget Parameters Overview directly. Reach for a config script only when the standard parameters are insufficient.

How config scripts are loaded

The advScript widget parameter value is passed into the board widget and exposed as window.__pbAdvScript. The Planningboard scheduler reads this property during initialization and evaluates it after the initial configuration object is assembled but before the board renders.

  Widget parameter editor
         |
         | advScript = "window.__pbConfig.maxItems = 500;"
         v
  Planningboard widget iframe
         |
         | window.__pbAdvScript evaluated at schedulerInit
         v
  Config object modified  -->  Board renders with updated config

Step-by-step: adding a config script

Navigate to the Polarion LiveDoc or Wiki page that hosts the Planningboard widget. Switch to edit mode and open the widget parameters panel.

2. Locate the Advanced Script parameter

In the widget parameters editor, find the field labelled Advanced Script (mapped to the advScript parameter). This is a free-text field that accepts JavaScript.

The Advanced Script field accepts raw JavaScript. There is no syntax validation in the editor. A syntax error in your script will silently prevent the script from running. Check the browser console for errors if the board behaves unexpectedly after adding a script.

3. Write your script

Your script runs in the widget frame’s JavaScript context. The Planningboard configuration object is accessible as window.__pbConfig. Modify properties on this object directly. Example: override the maximum number of work items

if (window.__pbConfig) {
  window.__pbConfig.maxItems = 500;
}

Example: conditionally enable capacity load based on a URL parameter

if (window.__pbConfig) {
  var params = new URLSearchParams(window.location.search);
  if (params.get('showCapacity') === 'true') {
    window.__pbConfig.capacityLoad = true;
  }
}

Example: set the hours-per-day value for capacity calculations

if (window.__pbConfig) {
  window.__pbConfig.hoursPerDay = 6;
}

Always guard your script with if (window.__pbConfig). If the board fails to initialize for any reason, window.__pbConfig may be undefined, and an unguarded access will throw a JavaScript error that can mask the real problem.

Save the widget configuration. Reload the Planningboard page to verify the script takes effect.

Configuration properties available in `window.__pbConfig`

The following properties are confirmed present in the configuration object. Use their exact names — incorrect casing or spelling will produce no effect (the property will be ignored silently).

Property	Type	Default	Description
`maxItems`	number	`1000`	Maximum number of work items loaded onto the board
`capacityLoad`	boolean	`false`	Enables capacity loading calculations
`multiCapacityLoad`	boolean	`false`	Enables per-resource capacity loading across multiple plans
`userCapacityLoad`	boolean	`false`	Enables user-level capacity loading when using the Teams service
`hoursPerDay`	number	`8`	Working hours per day used in capacity calculations
`useTeamsService`	boolean	`false`	Enables integration with the Polarion Teams service
`capacityField`	string	`null`	Custom field ID containing capacity values (for example story points or hours)
`lastPlans`	number	`1`	Number of past plans to display as columns
`nextPlans`	number	`5`	Number of future plans to display as columns

When setting capacityField or similar string-typed properties via a config script, ensure there are no leading or trailing spaces in the value. Whitespace in field IDs causes silent lookup failures.

Common pitfalls

Script does not run

Check the browser console for JavaScript syntax errors. A missing semicolon or unmatched bracket prevents the entire script from executing. Also confirm the script is saved in the advScript parameter, not in a different parameter field.

Property change has no visible effect

Some properties are consumed during an initialization phase that has already passed by the time the script runs. If a property change does not take effect, the property may not be modifiable via config script — consult the Widget Parameters Overview for the canonical way to set that value.

Board shows wrong capacity after script change

Capacity configuration involves several interacting properties (capacityLoad, multiCapacityLoad, userCapacityLoad, hoursPerDay, capacityField). Setting one without the others may produce unexpected results. See Configure Capacity Tracking for the full configuration sequence.

Script conflicts with page parameters

If you are also using Use Page Parameters or Scripted Page Parameters, be aware that page parameters are resolved server-side before the board widget is rendered, while the config script runs client-side. The config script runs after page parameter substitution, so it can read but not undo parameter-derived values.

Verification

After saving your config script and reloading the board, you should see the board render with the modified behaviour. To confirm the script ran:

Open browser developer tools (F12).
In the Console, type window.__pbConfig and press Enter.
Inspect the configuration object — the properties you modified should reflect the values set in your script.

If the object shows the original values, the script did not execute. Check the Console for errors.

What is a config script?

When to use config scripts

How config scripts are loaded

Step-by-step: adding a config script

1. Open the widget parameter editor

2. Locate the Advanced Script parameter

3. Write your script

4. Save the widget parameters

Configuration properties available in `window.__pbConfig`

Common pitfalls

Script does not run

Property change has no visible effect

Board shows wrong capacity after script change

Script conflicts with page parameters

Verification

See also

​What is a config script?

​When to use config scripts

​How config scripts are loaded

​Step-by-step: adding a config script

​1. Open the widget parameter editor

​2. Locate the Advanced Script parameter

​3. Write your script

​4. Save the widget parameters

​Configuration properties available in window.__pbConfig

​Common pitfalls

​Script does not run

​Property change has no visible effect

​Board shows wrong capacity after script change

​Script conflicts with page parameters

​Verification

​See also

What is a config script?

When to use config scripts

How config scripts are loaded

Step-by-step: adding a config script

1. Open the widget parameter editor

2. Locate the Advanced Script parameter

3. Write your script

4. Save the widget parameters

Configuration properties available in `window.__pbConfig`

Common pitfalls

Script does not run

Property change has no visible effect

Board shows wrong capacity after script change

Script conflicts with page parameters

Verification

See also