> ## 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.
# Dynamic Filtering with Page Parameters
> Configure a single Nextedy PLANNINGBOARD page that adapts its swimlane filter dynamically based on a page parameter, so different teams or roles can use the same board without maintaining separate per-team pages.
## What you will achieve
By the end of this guide you will have a Planningboard widget that reads a team or role identifier from a Polarion page parameter and applies it as a swimlane filter at load time. Users who need a different team view change the parameter value in the page URL or the page parameter widget — no widget reconfiguration required.
## Prerequisites
* A Planningboard widget already embedded in a Polarion LiveDoc or Wiki page.
* The swimlane **Assignment Mode** set to `ASSIGNEE` or `ENUM` on that widget (page parameters for swimlane filtering apply to these modes).
* If you plan to filter by Nextedy Team work items: the Team work item type ID in your Polarion project must be exactly `team` (hard-coded constraint — see [Common pitfalls](#common-pitfalls)).
***
## How page parameters work with Planningboard
Polarion pages support **page parameters**: named string values passed to every widget on the page. Planningboard reads these values from the page context and can use them to control the swimlane filter (`selectedTeam` or a resource field filter) at render time.
The parameter value is a **string** entered manually (a dropdown enum picker for page parameters is under investigation by the support team — see the note at the end of this page). Plan your parameter names and values to be human-readable, since users will type or copy them.
***
1. Open the LiveDoc or Wiki page that contains the Planningboard widget in **Edit** mode.
2. Insert a **Page Parameters** widget (Polarion built-in) somewhere on the page — typically above the board.
3. Define a parameter. For team-based filtering, a sensible name is `teamId`. Set a default value if you have a primary team.
The page parameter widget stores the name-value pair and exposes it to all other widgets on the same page.
***
Open the Planningboard widget's configuration panel.
### For ASSIGNEE mode — filtering by selected team
Set the **Selected Team** field (`selectedTeam` property) to reference your page parameter using the Polarion page-parameter expression syntax:
```properties theme={null}
selectedTeam = ${pageParam.teamId}
```
Replace `teamId` with the exact parameter name you defined in Step 1.
When `useTeamsService = true` is also enabled, the `selectedTeam` value is matched against the Teams Service team IDs. Ensure the parameter value your users supply matches the team ID exactly (case-sensitive).
### For ENUM mode — filtering by a resource field value
If your swimlanes are driven by an enum field (for example a `team` custom field on work items), set the resource field and then constrain which enum values appear as swimlanes by referencing the page parameter in the **Rows Filter** field:
```properties theme={null}
resourceField = team
rowsFilter = ${pageParam.teamId}
```
The value entered into the page parameter must match the enum option ID exactly, including casing. A value of `Alpha` will not match an option with ID `alpha`. Communicate the exact expected values to your users.
***
1. Save the page.
2. With the default parameter value in place, the board should load showing only the swimlanes that match.
3. Change the parameter value in the Page Parameters widget to a different team ID and reload — the swimlanes should update to reflect the new value.
Polarion page parameters can also be supplied via the page URL (the exact syntax depends on your Polarion version). This means you can share a URL like `?teamId=beta` with a colleague and they will land directly on the filtered board view.
***
If you want the board to default to a team based on the current user's Polarion role — without the user having to enter anything — add a **Scripted Page Parameter** widget instead of (or alongside) the plain page parameter.
The script reads the current user's roles from the Polarion context and maps them to a team ID:
```javascript theme={null}
// Example: map Polarion role to a team ID
var roleToTeam = {
"team_alpha_member": "alpha",
"team_beta_member": "beta"
};
var roles = $user.getRoles($project.id);
var teamId = "all"; // default when no role matches
for (var i = 0; i < roles.length; i++) {
var mapped = roleToTeam[roles[i]];
if (mapped) { teamId = mapped; break; }
}
teamId; // last expression is the parameter value returned
```
Set the **Output Parameter Name** on the scripted widget to `teamId` so it feeds the same parameter name that the Planningboard widget reads.
See [Scripted Page Parameters](/planningboard/guides/advanced/scripted-page-parameters) for the full scripted widget API and additional examples.
***
## Configuration reference
| Property | Type | Default | Purpose in this guide |
| ----------------- | ------- | ---------- | ------------------------------------------------------------------------ |
| `selectedTeam` | string | `None` | ID of the team to filter swimlanes; accepts `${pageParam.*}` expressions |
| `useTeamsService` | boolean | `false` | Must be `true` when `selectedTeam` refers to a Teams Service team |
| `assignmentMode` | string | `ASSIGNEE` | Set to `ASSIGNEE` for user swimlanes or `ENUM` for field-based swimlanes |
| `resourceField` | string | `None` | Custom field ID used for ENUM-mode swimlane grouping |
***
## Common pitfalls
When using the Nextedy Teams Service integration, the work item type ID for your Team work items must be the literal string `team`. This is a hard-coded constraint in the product. If your project uses a different type ID (e.g. `agile_team`), the Teams Service integration will not locate your team work items correctly. Rename the type or contact support.
Page parameters for swimlane filtering accept only a manually entered string value. An enum picker (dropdown) for page parameters is under investigation by the product team. Until it ships, users must type or paste the exact team or enum ID. Document the valid values prominently on the page (for example, in a text block above the board) to reduce entry errors.
The expression `${pageParam.teamId}` is case-sensitive. If you define the parameter as `TeamId` in Step 1 but reference it as `${pageParam.teamId}`, the value will not be substituted and the filter will be empty or use the literal string. Keep parameter names lowercase and consistent.
***
## You should now see...
After completing these steps:
* The Planningboard loads with swimlanes filtered to the team or resource identified by the current page parameter value.
* Changing the page parameter value (either in the Page Parameters widget or via URL) causes the board to reload showing only the matching swimlanes.
* If you added a scripted parameter, the board defaults automatically to the team matching the current user's role, with no manual entry required.
If swimlanes are not filtering as expected, check: (1) the parameter name in the Page Parameters widget matches exactly the name used in `${pageParam.*}`; (2) the parameter value matches the team ID or enum option ID exactly; (3) `useTeamsService` is set correctly for your assignment mode.
***
## See also
* [Use Page Parameters](/planningboard/guides/configuration/page-parameters) — full reference for Polarion page parameters and Planningboard integration
* [Scripted Page Parameters](/planningboard/guides/advanced/scripted-page-parameters) — role-aware and computed parameter values via Velocity scripts
* [User and Assignee Swimlanes](/planningboard/guides/swimlanes/user-swimlanes) — configuring ASSIGNEE mode swimlanes
* [Enumeration Field Swimlanes](/planningboard/guides/swimlanes/enum-swimlanes) — configuring ENUM mode swimlanes
* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) — complete widget parameter reference
**KB Articles**
* Planningboard Widget Parameters
* Planningboard: Customizable Statistics and Capacity Indicators
**Support Tickets**
* [#6509](https://support.nextedy.com/helpdesk/tickets/6509)
* [#6309](https://support.nextedy.com/helpdesk/tickets/6309)
**Source Code**
* `Config.java`
* `PlanningBoardViewServlet.java`
* `PlanningBoardWidget.java`
* `PlanningBoardWidgetRenderer.java`
* `PlanningBoardWidgetDependenciesProcessor.java`