Scripted Page Parameters

​

What this guide covers

​

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 and Use Page Parameters.

1

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.

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.

---

2

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:

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

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.

---

3

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.

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.

---

4

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:

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

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.

---

5

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 and Track Team Capacity.

---

​

Configuration example — single board, three teams

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
]

​

Common pitfalls

​

Verification

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.

​

See also

• Use Page Parameters — static page parameters without scripting
• Dynamic Filtering with Page Parameters — URL-driven parameter patterns
• Configure Plans (Columns) — plansQuery and Plans Mode options
• Set Up Teams Service — prerequisite for selectedTeam and capacity filtering
• Config Scripts — server-side scripts that modify the full board configuration object
• Script Errors — diagnosing failures in scripted page parameter blocks