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

# Scripted Page Parameters

> Use Polarion Scripted Page Parameters to drive Nextedy PLANNINGBOARD widget properties dynamically — eliminating hardcoded values and letting a single board page adapt to the current user, role, or team.

## What this guide covers

Polarion's Scripted Page Parameters (documented in the Polarion Widget SDK, section 7.2) let a Wiki page compute parameter values at render time using a server-side script. When combined with Planningboard's widget parameters — such as `selectedTeam`, `assignmentMode`, or swimlane filters — this means one board page can serve multiple teams or roles without duplicating the page for every audience.

A common scenario: your project has several teams and you want each team member who opens the board to see only their own swimlane, without an administrator manually maintaining ten near-identical pages.

## Prerequisites

* Planningboard is installed and a board widget is already embedded on a Polarion Wiki page.
* You have Wiki page edit permissions in Polarion.
* You understand the basic Planningboard widget parameters. See [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) and [Use Page Parameters](/planningboard/guides/configuration/page-parameters).

***

<Steps>
  <Step title="Understand how Scripted Page Parameters work">
    A Scripted Page Parameter is a page-level script block that Polarion evaluates before rendering the page. The script produces a map of key/value pairs. Those values are then available to any widget on the page as named parameters — exactly as if a user had typed them into the widget's parameter editor.

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/zUlmOSLBIQ0HyaAX/planningboard/diagrams/guides/advanced/scripted-page-parameters/diagram-1.svg?fit=max&auto=format&n=zUlmOSLBIQ0HyaAX&q=85&s=f9baec2fe50f43f206f0d559abdd550f" alt="Flow from Polarion Wiki page load through the Scripted Page Parameters script evaluating server-side to produce key=value parameters, to the Planningboard widget rendering with those dynamic values" width="660" height="300" data-path="planningboard/diagrams/guides/advanced/scripted-page-parameters/diagram-1.svg" />
    </Frame>

    The script has access to the Polarion server context, including the current user object and their roles and group memberships. This is what enables role-aware or team-aware board filtering.

    ***
  </Step>

  <Step title="Add a Scripted Page Parameter block to your Wiki page">
    Open the Wiki page that contains your Planningboard widget for editing. In the page source, add a Scripted Page Parameters block **before** the widget macro. In Polarion Wiki markup, this is a `module-scriptedparams` macro or an equivalent script block — refer to your Polarion version's Widget SDK for the exact syntax.

    The script block returns a `Map<String, String>`. Each key becomes a named parameter you can reference in widget configuration.

    Example: mapping the current user's role to a team ID:

    ```javascript theme={null}
    // Scripted Page Parameters script — runs server-side at page load
    def user = polarionContext.user
    def teamId = "unassigned"

    if (user.hasRole("team-alpha")) {
        teamId = "alpha"
    } else if (user.hasRole("team-beta")) {
        teamId = "beta"
    } else if (user.hasRole("team-gamma")) {
        teamId = "gamma"
    }

    return ["boardTeam": teamId]
    ```

    This produces the parameter `boardTeam` with a value derived from the current user's Polarion role — no role IDs are exposed to end users.

    <Warning title="Role ID casing is exact">
      Polarion role IDs are case-sensitive. Use the exact role ID string as it appears in **Administration > Roles**, not the display label. A mismatch produces no error — the condition simply never matches, and the parameter falls back to your default value.
    </Warning>

    ***
  </Step>

  <Step title="Reference the parameter in the Planningboard widget">
    Once the script produces a named parameter, reference it inside the Planningboard widget configuration using Polarion's standard `${paramName}` substitution syntax.

    For example, to pass `boardTeam` into the `selectedTeam` widget property:

    | Widget property | Value          |
    | --------------- | -------------- |
    | `selectedTeam`  | `${boardTeam}` |

    You can use the same parameter in multiple widget properties. For instance, you could drive both the `selectedTeam` and a plan query filter from the same scripted value.

    <Tip title="Use a safe default in the script">
      Always initialise the output variable before the conditional logic (as shown in Step 2). If no role condition matches, the widget receives the default value rather than an empty or null string, which could cause unexpected board behaviour.
    </Tip>

    ***
  </Step>

  <Step title="Use a parameter in the Plan query">
    The `plansQuery` property accepts a Lucene query string and also supports `${param}` substitution. This lets the script constrain which Plans appear as columns for the current user.

    Example: show only plans belonging to the user's team prefix:

    ```javascript theme={null}
    // Script
    def user = polarionContext.user
    def planPrefix = "all"

    if (user.hasRole("team-alpha")) {
        planPrefix = "alpha"
    } else if (user.hasRole("team-beta")) {
        planPrefix = "beta"
    }

    return ["teamPlanPrefix": planPrefix]
    ```

    Widget configuration:

    | Widget property | Value                   |
    | --------------- | ----------------------- |
    | `plansQuery`    | `id:${teamPlanPrefix}*` |

    When `teamPlanPrefix` resolves to `alpha`, the board loads only Plans whose ID starts with `alpha`.

    <Warning title="Whitespace in query values breaks Lucene">
      If your scripted value might contain spaces (e.g. a team name used directly in a query), wrap it in quotes inside the query string: `id:"${teamPlanPrefix}"`. Unquoted spaces split the Lucene term and produce unexpected results. Capacity configuration parameters are also whitespace-sensitive — test with values that include spaces before deploying.
    </Warning>

    ***
  </Step>

  <Step title="Combine with the `selectedTeam` property for capacity filtering">
    When your board uses the Teams Service (`useTeamsService = true`), the `selectedTeam` property determines which team's capacity is loaded. Driving this from a scripted parameter means the capacity bar automatically reflects the current user's team without them selecting it manually.

    | Widget property   | Value          |
    | ----------------- | -------------- |
    | `useTeamsService` | `true`         |
    | `selectedTeam`    | `${boardTeam}` |

    For background on the Teams Service and capacity configuration, see [Set Up Teams Service](/planningboard/guides/capacity/teams-service-setup) and [Track Team Capacity](/planningboard/guides/capacity/team-capacity).

    ***
  </Step>
</Steps>

## Configuration example — single board, three teams

The following shows the complete setup for a project with three teams (`alpha`, `beta`, `gamma`), each with a matching Polarion role:

**Scripted Page Parameters script:**

```javascript theme={null}
def user = polarionContext.user
def teamId = "all"
def planPrefix = "all"

if (user.hasRole("team-alpha")) {
    teamId = "alpha"
    planPrefix = "alpha"
} else if (user.hasRole("team-beta")) {
    teamId = "beta"
    planPrefix = "beta"
} else if (user.hasRole("team-gamma")) {
    teamId = "gamma"
    planPrefix = "gamma"
}

return [
    "boardTeam": teamId,
    "teamPlanPrefix": planPrefix
]
```

**Planningboard widget properties (relevant excerpt):**

| Property          | Value                   |
| ----------------- | ----------------------- |
| `useTeamsService` | `true`                  |
| `selectedTeam`    | `${boardTeam}`          |
| `plansQuery`      | `id:${teamPlanPrefix}*` |
| `assignmentMode`  | `ASSIGNEE`              |

With this configuration, a user holding the `team-alpha` role sees only `alpha*` Plans as columns and the capacity bar reflects the alpha team's capacity. Users with no matching role see all Plans (`id:all*`) — adjust the fallback to your project's needs.

***

## Common pitfalls

<Warning title="Parameter not defined results in literal `${paramName}` on the board">
  If the scripted parameter block fails to execute or the key is misspelled, Polarion passes the raw `${boardTeam}` string to the widget. The board may load with an unresolved query. Check the page script for syntax errors and confirm the parameter name matches exactly (case-sensitive) between the script return map and the widget property value.
</Warning>

<Warning title="Script errors are silent to end users">
  A runtime error in the script block may silently return an empty map, leaving all widget properties that depend on scripted values unresolved. Enable Polarion server logging during setup, or add a fallback default before every return statement.
</Warning>

<Tip title="Test with a fixed parameter first">
  Before wiring up the full role-to-value logic, hardcode a known-good value in the script and confirm the widget responds correctly. Once the widget reads the parameter as expected, replace the hardcoded value with the conditional logic.
</Tip>

***

## Verification

After saving the page and refreshing in a browser:

1. Open the board as a user who holds one of the mapped roles.
2. Confirm the columns show only the Plans matching that team's prefix.
3. If `useTeamsService` is enabled, confirm the capacity bar reflects that team's capacity.
4. Open the board as a second user with a different role and verify the board shows a different set of Plans.

You should now see the board adapting its content to each user's role without any manual filter selection.

***

## See also

* [Use Page Parameters](/planningboard/guides/configuration/page-parameters) — static page parameters without scripting
* [Dynamic Filtering with Page Parameters](/planningboard/guides/advanced/dynamic-filtering) — URL-driven parameter patterns
* [Configure Plans (Columns)](/planningboard/guides/configuration/plans-configuration) — `plansQuery` and Plans Mode options
* [Set Up Teams Service](/planningboard/guides/capacity/teams-service-setup) — prerequisite for `selectedTeam` and capacity filtering
* [Config Scripts](/planningboard/guides/advanced/config-scripts) — server-side scripts that modify the full board configuration object
* [Script Errors](/planningboard/guides/troubleshooting/script-errors) — diagnosing failures in scripted page parameter blocks

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

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

  **Support Tickets**

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

  **Source Code**

  * `Config.java`
  * `viewSetup.vm`
  * `PlanningBoardViewServlet.java`
  * `PlanningService.java`
  * `PlanningBoardWidget.java`
</Accordion>