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

> Use a config script to modify the Nextedy PLANNINGBOARD widget configuration programmatically at render time — override properties, adjust capacity settings, or apply conditional logic before the board loads.

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

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

## 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](/planningboard/guides/configuration/widget-parameters) 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.

```text theme={null}

  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

### 1. Open the widget parameter editor

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.

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

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

```javascript theme={null}
if (window.__pbConfig) {
  window.__pbConfig.maxItems = 500;
}
```

**Example: conditionally enable capacity load based on a URL parameter**

```javascript theme={null}
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**

```javascript theme={null}
if (window.__pbConfig) {
  window.__pbConfig.hoursPerDay = 6;
}
```

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

### 4. Save the widget parameters

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                                   |

<Warning title="Capacity parameters are whitespace-sensitive">
  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.
</Warning>

## 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](/planningboard/guides/configuration/widget-parameters) 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](/planningboard/guides/configuration/capacity-configuration) for the full configuration sequence.

### Script conflicts with page parameters

If you are also using [Use Page Parameters](/planningboard/guides/configuration/page-parameters) or [Scripted Page Parameters](/planningboard/guides/advanced/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:

1. Open browser developer tools (F12).
2. In the Console, type `window.__pbConfig` and press Enter.
3. 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.

## See also

* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) — all standard widget parameters and their defaults
* [Item Scripts](/planningboard/guides/advanced/item-scripts) — scripts that run per work-item card, for dynamic card content
* [Data Scripts](/planningboard/guides/advanced/data-scripts) — scripts for transforming the work item dataset before the board renders
* [Scripted Page Parameters](/planningboard/guides/advanced/scripted-page-parameters) — server-side parameter scripting complementary to config scripts
* [Dynamic Filtering with Page Parameters](/planningboard/guides/advanced/dynamic-filtering) — using URL parameters to drive board configuration
* [Script Errors](/planningboard/guides/troubleshooting/script-errors) — diagnosing and resolving script execution errors

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

  * Planningboard Widget Parameters
  * Planningboard: Customizable Statistics and Capacity Indicators
  * Troubleshooting Script Errors in Planningboard

  **Support Tickets**

  * [#6174](https://support.nextedy.com/helpdesk/tickets/6174)
  * [#5879](https://support.nextedy.com/helpdesk/tickets/5879)

  **Source Code**

  * `viewSetup.vm`
  * `Config.java`
  * `PlanningBoardWidgetRenderer.java`
  * `Item.java`
  * `planningboard.js`
</Accordion>