> ## 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.
# Configure Work Items Dataset
> Configure which work items appear on your Nextedy PLANNINGBOARD, how they are sorted, what dependency links are visualized, and which fields show in the sidebar preview.
## Before you start
* You have an existing Planningboard widget embedded in a Polarion LiveDoc or Wiki page.
* You can open the widget's configuration panel (expand the widget tools, then click **Edit**).
* You know the Lucene query syntax used in Polarion for filtering work items.
***
1. Navigate to the Polarion page that contains your Planningboard widget.
2. Expand the widget toolbar and click the **Edit** (pencil) icon to open the configuration panel.
3. In the configuration panel, locate the **Parameters for Work Items** section.
***
The **Scope** field defines which Polarion project (or project group) provides work items for this board instance.
* Set **Scope** to the project ID you want the board to draw work items from.
* Leave blank to use the project the page lives in.
When you embed the same board template in multiple projects, leaving **Scope** blank lets each instance automatically draw from its own project.
***
The **Query** field contains a Lucene query that filters which work items are loaded onto the board. The default value in the configuration is `NOT *:*`, which matches nothing — you must set an explicit query.
**Query type** controls how the query string is interpreted:
| Query Type | Use when |
| ---------- | ------------------------------------------------------ |
| Lucene | You want full Lucene query syntax (recommended) |
| SQL-like | You prefer a simplified SQL-like Polarion query format |
**Example queries:**
```text theme={null}
# All user stories and tasks not yet closed
(type:story OR type:task) AND NOT status:closed
# All items in a specific severity category
severity:must_have AND NOT status:done
# Items assigned to a specific user
assignee.id:jsmith AND NOT status:verified
```
**Add Planned** — enable this option to load all work items that are already planned into any Plan, in addition to items matching the **Type** and **Query** fields. Use this when you want the board to show a complete picture of both backlog and already-scheduled items.
The `maxItems` configuration property defaults to `1000`. If your query matches more than 1000 work items, only the first 1000 are loaded. Narrow your query or request a `maxItems` increase from your Polarion administrator if you need more items.
The default query `NOT *:*` intentionally returns no results. After creating a new widget, the board will appear empty until you set a valid query.
***
Use the **Work Item Type** field (`wiType`) to restrict the board to a single work item type, such as `story`, `task`, or `feature`. This is equivalent to adding `type:` to your query but is applied as a separate filter.
* Leave blank to show all types matching the query.
* Set to a single type ID (e.g. `story`) to narrow the dataset.
When using enum-based swimlanes, the available enum values in the rows filter change based on the selected work item type. Different types may have different enumeration configurations — set **Work Item Type** explicitly to ensure the swimlane options match your dataset.
***
The **Sort by** field defines the initial ordering of cards on the board. Cards are sorted within each swimlane according to this setting.
In the current version of Planningboard, the swimlane sort order is coupled to the item sort order. Changing **Sort by** affects how items appear within each swimlane row, not just globally. There is no independent swimlane sort separate from item sort.
***
The **Dependency Roles** field specifies which Polarion work item link roles are visualized as dependency arrows between cards on the board.
* Enter one or more link role IDs (as configured in your Polarion project).
* Dependencies are only shown visually when the **Show Dependencies** toolbar button is toggled on.
**Example:** If your project uses `depends_on` as a link role ID:
```text theme={null}
depends_on
```
The **Show Dependencies** toolbar button must be enabled for arrows to appear. Dependency roles must already exist in your Polarion project's link role configuration — Planningboard does not create link roles.
***
When a user clicks on a card, the **Work Item Properties** sidebar opens. The **Sidebar Fields** parameter controls which fields appear by default in that sidebar.
* Default fields: `title`, `status`, `plannedIn`
* Enter additional field IDs separated by the configured delimiter.
**Example sidebar fields configuration:**
```text theme={null}
title, status, plannedIn, severity, assignee
```
Users can further customize their own sidebar view using the **Select Fields** (gear icon) button in the sidebar. Personal field selections apply only to that user and affect all work items of the same type.
***
1. Save the widget configuration.
2. Reload the Planningboard page.
You should now see cards populating the board according to your query and filters. The sidebar of any clicked card should show the fields you configured.
If you see no cards after saving, check:
* The **Query** field is not still set to `NOT *:*` (the default).
* The **Scope** project contains work items matching your query.
* The **Work Item Type** filter is not excluding all items.
* The `maxItems` limit (default: 1000) has not been silently hit.
***
## Configuration example
The following widget parameter values set up a board for a sprint team working with user stories:
| Parameter | Example value |
| ---------------- | ---------------------------------------------- |
| Scope | `MyProject` |
| Query type | Lucene |
| Query | `type:story AND NOT status:closed` |
| Work Item Type | `story` |
| Add Planned | enabled |
| Sort by | `priority` |
| Dependency Roles | `depends_on` |
| Sidebar Fields | `title, status, plannedIn, assignee, severity` |
***
## Known limitations
* **Custom Team work item types** are not supported for swimlane configuration in Planningboard. If your project uses a custom Team work item type (rather than the standard Nextedy Team work item with required custom fields), swimlane assignment by team is not available. Use Nextedy GANTT (version 25.5.0 and later) if you need custom Team work item type support.
* **Page parameters in work item queries** — dynamic filtering via Polarion page parameters (e.g., `$pageParameters.xxx`) in the swimlane row configuration is not supported. As a workaround, configure a separate Planningboard page per team using static link roles.
* **Multi-assignee capacity** — Planningboard assigns each work item to a single resource for capacity purposes. Multi-assignee capacity distribution (as available in Nextedy GANTT) is not currently supported.
***
## See also
* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters)
* [Configure Plans (Columns)](/planningboard/guides/configuration/plans-configuration)
* [Configure Swimlanes (Rows)](/planningboard/guides/configuration/swimlanes-configuration)
* [Configure Unplanned Sidebar](/planningboard/guides/configuration/unplanned-sidebar)
* [Configure Dependencies Display](/planningboard/guides/configuration/dependencies-configuration)
* [Use Page Parameters](/planningboard/guides/configuration/page-parameters)
* [Dynamic Filtering with Page Parameters](/planningboard/guides/advanced/dynamic-filtering)
**KB Articles**
* Planningboard Widget Parameters
* Planningboard: Customizable Statistics and Capacity Indicators
* Planningboard interface & basic interactions
**Support Tickets**
* [#6174](https://support.nextedy.com/helpdesk/tickets/6174)
* [#6496](https://support.nextedy.com/helpdesk/tickets/6496)
* [#6546](https://support.nextedy.com/helpdesk/tickets/6546)
**Source Code**
* `PlanningBoardWidget.java`
* `widget.vm`
* `Config.java`
* `viewSetup.vm`
* `PlanningBoardWidgetRenderer.java`