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

# Data Scripts

> Use data scripts to customise how Nextedy PLANNINGBOARD loads, filters, and transforms work items and plans before they reach the board.

## Overview

Data scripts run server-side during the board rendering lifecycle. They let you intercept the data pipeline — adjusting queries, modifying assignment logic, or reshaping the items that appear in swimlanes and columns — without touching widget parameters.

```text theme={null}
  Widget Parameters
        |
        v
  +-------------------+          +-------------------+
  |  Plan Query       |          |  Work Item Query  |
  |  (plansQuery)     |          |  (query)          |
  +-------------------+          +-------------------+
        |                               |
        v                               v
  +---------------------------------------------------+
  |              Data Script Hook                     |
  |   (runs before data reaches the board renderer)   |
  +---------------------------------------------------+
        |
        v
  +---------------------------------------------------+
  |  Board Renderer — swimlanes, cards, capacity bars |
  +---------------------------------------------------+
```

## Before You Begin

* You need access to the Planningboard widget configuration on a Polarion LiveDoc or Wiki page.
* Data scripts are Groovy/Velocity expressions evaluated on the Polarion server. Syntax errors surface as board-level error messages; see [Script Errors](/planningboard/guides/troubleshooting/script-errors) for how to diagnose them.
* Review the widget parameters your board already uses — data scripts augment, not replace, them. See [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters).

<Steps>
  <Step title="Locate the Script Field in the Widget">
    1. Open the Polarion page containing the Planningboard widget.
    2. Enter edit mode and open the widget's parameter panel.
    3. Scroll to the **Advanced** section. The script fields are listed there.

    <Info title="Verify in application">
      The exact field label for data scripts in the widget parameter panel — confirm it against the live product before relying on the label shown here.
    </Info>
  </Step>

  <Step title="Understand the Data Pipeline Properties">
    The following properties from the board configuration control how data is loaded. Data scripts operate within the bounds these properties establish.

    | Property         | Default         | Description                                                                                                                            |
    | ---------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
    | `query`          | `NOT *:*`       | Lucene query filtering the work items displayed on the board.                                                                          |
    | `plansQuery`     | *(none)*        | Lucene query filtering which Plans are shown as columns.                                                                               |
    | `plansMode`      | `PROJECT_PLANS` | How plans are generated — project plans, SAFe sprints, SAFe program increments, or custom stemming.                                    |
    | `assignmentMode` | `ASSIGNEE`      | How work items map to swimlanes — `ASSIGNEE`, `ENUM`, `PARENT`, `PROJECT`, `SAFE_TEAM`, `SAFE_TRAIN_TEAM`, `SAFE_PROGRAMS`, or `none`. |
    | `resourceField`  | *(none)*        | Custom field ID used when `assignmentMode` is `ENUM`.                                                                                  |
    | `maxItems`       | `1000`          | Maximum work items loaded per render.                                                                                                  |
    | `wiType`         | *(none)*        | Work item type filter (e.g. `task`, `story`, `feature`).                                                                               |
    | `lastPlans`      | `1`             | Number of past plans to show.                                                                                                          |
    | `nextPlans`      | `5`             | Number of upcoming plans to show.                                                                                                      |

    <Warning title="Whitespace sensitivity">
      Capacity-related configuration properties are whitespace-sensitive. Trailing spaces in property values cause silent miscalculations. Always copy property names exactly as shown — do not add spaces before or after `=` separators.
    </Warning>
  </Step>

  <Step title="Write a Data Script">
    Data scripts can reference the above properties to apply runtime logic. A typical pattern adjusts the work item query based on context — for example, restricting items to a specific type or excluding resolved items.

    **Example: restrict the board to unresolved stories**

    ```text theme={null}
    type:story AND NOT status:resolved
    ```

    Place this expression in the work item **Query** field. This is a Lucene query — not a script — but the same field accepts scripted expressions when page parameters are involved. For dynamic filtering using page parameters, see [Dynamic Filtering with Page Parameters](/planningboard/guides/advanced/dynamic-filtering).

    **Example: filter Plans by a date-range expression**

    ```text theme={null}
    template.id:iteration AND dueDate:[NOW-90DAYS TO NOW+90DAYS]
    ```

    Set this in the **Plans** query field. The Plans Type must be set to **Project Plans** (`PROJECT_PLANS`) for a plain Lucene `plansQuery` to take effect; SAFe modes auto-set their own plan filters.
  </Step>

  <Step title="Control Assignment at Data Load Time">
    When the Assignment Type is set to **Enumeration Field** (`ENUM`), the board groups cards by an enumeration field. To restrict which enum values appear as swimlanes, use the swimlane filtering options rather than a data script — see [Enumeration Field Swimlanes](/planningboard/guides/swimlanes/enum-swimlanes).

    When the Assignment Type is set to **Parent Item** (`PARENT`), the board groups cards under parent work items matched by a Lucene query. Supply that query in the parent-query field.

    <Warning title="Parent Item mode does not support normalization">
      `assignmentMode = PARENT` is incompatible with `planCellsMode`. Enabling both produces undefined layout behavior. Use the **Users (Assignee)** (`ASSIGNEE`) or **Enumeration Field** (`ENUM`) mode if you need capacity normalization across swimlanes.
    </Warning>
  </Step>

  <Step title="Configure Capacity Data Loading">
    Capacity-aware data loading is controlled by three boolean properties. Set them in the widget parameters panel:

    | Property            | Default | When to enable                                                                                      |
    | ------------------- | ------- | --------------------------------------------------------------------------------------------------- |
    | `capacityLoad`      | `false` | Enable per-swimlane capacity bars (uses `remainingEstimate` / `initialEstimate` or a custom field). |
    | `multiCapacityLoad` | `false` | Enable per-resource capacity across multiple plans simultaneously.                                  |
    | `userCapacityLoad`  | `false` | Enable user-level capacity when Teams Service is active.                                            |

    To use a custom effort field instead of Polarion time-tracking fields, set `capacityField` to the custom field ID (for example, `storyPoints`). The `hoursPerDay` property (default `8`) converts time-based estimates to day units for the capacity bar.

    <Tip title="Teams Service unlocks richer capacity data">
      Setting `useTeamsService = true` activates the Teams Service integration, which provides team member lists, per-user capacity, and vacation data. This overrides `plan.capacity` values with team-sourced figures. See [Set Up Teams Service](/planningboard/guides/capacity/teams-service-setup) for the prerequisite configuration.
    </Tip>
  </Step>

  <Step title="Limit the Dataset for Performance">
    If the board renders slowly, lower `maxItems` (default `1000`). A tighter `query` or `wiType` filter reduces the working set more precisely than `maxItems` alone.

    ```text theme={null}
      Board load time factors:

      maxItems (1000 default)
           +
      Breadth of query
           +
      Number of plans (lastPlans + nextPlans)
           +
      capacityLoad / multiCapacityLoad (extra aggregation)

      ---> Total render time
    ```

    Reducing `nextPlans` from `5` to `3` — or narrowing `lastPlans` to `0` — noticeably cuts the plan-loading step.
  </Step>
</Steps>

## Verification

After saving the widget with your data script changes:

1. Exit edit mode and let the board reload.
2. Check that the swimlanes and columns show only the expected items.
3. If the board shows an error banner instead of cards, open browser developer tools and look for the script-error message, then consult [Script Errors](/planningboard/guides/troubleshooting/script-errors).

You should now see the board rendering only the work items and Plans that match your query and assignment configuration, with capacity bars (if enabled) reflecting the correct effort totals per swimlane.

<Warning title="SAFe modes override plansQuery">
  When the Plans Type is set to a SAFe value — **SAFe Sprints in Program** (`SAFE_SPRINTS`), **SAFe Sprints in Portfolio** (`SAFE_PFL_SPRINTS`), **SAFe Program Increments in Program** (`SAFE_PIS`), or **SAFe Program Increments in Solution** (`SAFE_SOLUTION`) — the plan filter is determined automatically from the SAFe Solution structure. A manually entered `plansQuery` value is ignored in these modes.
</Warning>

## See Also

* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) — full property reference
* [Config Scripts](/planningboard/guides/advanced/config-scripts) — board-level configuration scripting
* [Item Scripts](/planningboard/guides/advanced/item-scripts) — per-card scripting for appearance and content
* [Dynamic Filtering with Page Parameters](/planningboard/guides/advanced/dynamic-filtering) — pass runtime values into queries via URL parameters
* [Scripted Page Parameters](/planningboard/guides/advanced/scripted-page-parameters) — derive page parameter values programmatically
* [Configure Plans (Columns)](/planningboard/guides/configuration/plans-configuration) — plan query and column setup
* [Configure Work Items Dataset](/planningboard/guides/configuration/work-items-configuration) — query and type filter options
* [Script Errors](/planningboard/guides/troubleshooting/script-errors) — diagnosing and fixing script failures

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

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

  **Support Tickets**

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

  **Source Code**

  * `Config.java`
  * `viewSetup.vm`
  * `PlanningBoardWidgetRenderer.java`
  * `PlanningBoardWidget.java`
  * `PlanningBoardDataService.java`
</Accordion>