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

# Configuration

> Common questions about configuring Nextedy PLANNINGBOARD widget parameters, Plans modes, swimlane assignment types, and related settings.

***

## General Configuration

### Where do I configure Planningboard widget parameters?

All Planningboard configuration is done through the **Widget Parameters** panel of the Planningboard widget embedded in your Polarion LiveDoc or Wiki page. Open the widget's parameter editor to access sections for Work Items, Plans (Columns), Swimlanes (Rows), Queries, and New Plan. See the [Reference](/planningboard/reference/index) section for a full list of parameters.

### Which widget parameters control which work items appear on the board?

The **Work Items** section of Widget Parameters contains the key fields:

* `Scope` — defines the project scope for the current board
* `Query type` — sets the type of query to use
* `Query` — a Lucene query filtering which work items are shown (default: `NOT *:*`)
* `Add Planned` — when enabled, loads all planned items in addition to those matched by the query
* `Sort by` — defines how cards are ordered on the board

For details on Lucene query syntax in Polarion, refer to your Polarion documentation.

### What does the `Query` parameter default do, and why do I see no work items?

The default value of the `query` property is `NOT *:*`, which matches nothing. This is intentional — the widget ships without a pre-set query so that no items appear until you deliberately configure what to show. Set `Query` to a valid Lucene expression (for example, `type:story`) to populate the board with matching work items.

***

## Plans (Columns) Configuration

### How do I control which Plans appear as columns?

Use the **Plans (Columns)** section of Widget Parameters:

* `Plans Type` (`plansMode`) — selects the planning model: **Project Plans** (`PROJECT_PLANS`), **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`)
* `Plans` — defines which specific plans appear as columns
* `Show # of last plans` (`lastPlans`) — how many past/completed plans to display (default: 1)
* `Show # of next plans` (`nextPlans`) — how many upcoming plans to display (default: 5)
* `Show Capacity Load` (`capacityLoad`) — enables the capacity bar visualization per plan

<Note title="SAFe Plans Types">
  **SAFe Sprints in Program** (`SAFE_SPRINTS`), **SAFe Sprints in Portfolio** (`SAFE_PFL_SPRINTS`), **SAFe Program Increments in Program** (`SAFE_PIS`), and **SAFe Program Increments in Solution** (`SAFE_SOLUTION`) are SAFe-specific modes. Contact Nextedy support for configuration guidance if your organization uses SAFe.
</Note>

### What is the `Assign to Parent Plan` option and when should I enable it?

When `Assign to Parent Plan` is enabled, planning a work item into an iteration also automatically plans it into the parent Plan (for example, a Version). When disabled, the work item is only planned into the iteration you explicitly added it to. Enable this option when your project hierarchy requires parent Plans to reflect all work planned under them.

### Can I add a custom link to column (Plan) headers?

Yes. Use the `Report Link` field in the Plans (Columns) section. The link can be parameterized with plan variables. Example:

```
/polarion/#/project/${plan.objectId.projectId}/wiki/SOME_REPORT?plan=${plan.objectId.itemId}
```

This opens a report page filtered to the selected plan when you click the column header.

### Why does the configuration UI change when I switch Plans Type?

The widget dynamically shows or hides configuration fields based on the selected `Plans Type`. For example:

* **Project Plans** (`PROJECT_PLANS`) mode shows plan items configuration and the Sync to Parent option
* **SAFe Sprints in Program** (`SAFE_SPRINTS`) / **SAFe Sprints in Portfolio** (`SAFE_PFL_SPRINTS`) modes show the SAFe PI increment field instead
* Plan stemming fields appear only when stemming is enabled

This is by design — only the fields relevant to your selected mode are displayed.

```text theme={null}
Plans Type selected
        |
        +--- PROJECT_PLANS
        |         |-- Plan Items section  (visible)
        |         |-- Sync to Parent      (visible)
        |         |-- Plan Link field     (visible)
        |
        +--- SAFE_SPRINTS / SAFE_PFL_SPRINTS
        |         |-- SAFe PI Increment   (visible)
        |         |-- Plan Items section  (hidden)
        |
        +--- SAFE_PIS / SAFE_SOLUTION
                  |-- Portfolio config    (visible)
                  |-- Plan Items section  (hidden)
```

***

## Swimlanes (Rows) Configuration

### What swimlane assignment types are available?

The **Assignment Type** (`assignmentMode`) controls how the board is divided into rows:

| Assignment Type                                          | Groups swimlanes by                                |
| -------------------------------------------------------- | -------------------------------------------------- |
| Users (Assignee)                                         | Project members matching a configured role         |
| Parent Item                                              | Parent work items linked via a specified link role |
| Enumeration Field                                        | Values of a custom enumeration field (e.g. `team`) |
| Project                                                  | Sub-projects within the current project group      |
| SAFe types (Program/Solution Teams, ART Teams, Programs) | SAFe organizational units                          |
| No Swimlanes                                             | Disabled — all items in a single view              |

For a detailed guide on each type, see [Swimlanes FAQ](/planningboard/faq/swimlanes).

### How do I configure swimlanes by a custom field?

Set **Assignment Type** to `Enumeration Field` and provide the **Field ID** — the identifier of your custom enumeration field (for example, `team`). Optionally set **Rows Filter** to limit which field values appear as rows. Only `IEnumType` fields and list fields whose items are enum-typed are supported; `status`, `resolution`, and `type` fields are not supported as swimlane grouping fields.

### Does Planningboard support page parameters (e.g. `$pageParameters.xxx`) in swimlane configuration?

No. Planningboard swimlane configuration does not support Polarion page parameters for dynamic filtering. If you need per-team filtering, the current supported approaches are: configuring a separate Planningboard page per team (using static link roles), or using Nextedy GANTT, which supports custom Team work item types from version 25.5.0 onwards.

<Warning title="Custom Team work item types">
  Planningboard does not support custom Team work item types in swimlane configuration. If your project uses a non-standard Team work item type, use Nextedy Gantt (25.5.0+) as the primary planning tool for team-based solutions.
</Warning>

### Can I sort parent swimlanes by a custom property like priority?

Yes, from Planningboard 25.9.0. In the swimlane settings for **Parent Item** assignment type, set the **Sort By** field to the custom property you want to use (for example, priority). Earlier versions only supported a limited set of built-in sort options.

***

## Unplanned Section and Queries

### How do I add predefined queries to the Unplanned section?

Use the **Queries** section in Widget Parameters. Add one or more named queries (each with a label and a Lucene query expression). These appear as filter options in the Unplanned section's filter panel (funnel icon), letting users quickly switch to a specific subset of unplanned items — for example, all work items with status `reviewed`.

### How deep should I set `PARAMETER_US_DEPTH` for the Unplanned sidebar hierarchy?

`PARAMETER_US_DEPTH` controls how many levels of parent work items are loaded in the Unplanned sidebar. Deeper values give a richer hierarchy view but increase load time on large projects. Start with a value of 1 or 2; increase only if your planning process requires navigating multi-level parent hierarchies in the Unplanned panel. Set `PARAMETER_PARENTS_LINK_ROLE` to the link role that defines parent-child relationships in your project.

***

## Access and Licensing

### What can unlicensed users do on a Planningboard?

Unlicensed users have read-only access. They can view the full board content — including swimlanes, cards, and capacity data — but cannot:

* Create new Plans (the Create New Plan button is hidden)
* Show/hide the Unplanned section
* Use the sidebar to edit work item fields
* Drag and drop cards between swimlanes (moves are blocked and not persisted)

Licensed users have full editing capabilities. See [Licensing FAQ](/planningboard/faq/licensing) for more.

***

<Tip title="Configuration reference">
  For the full list of widget parameters with their default values and accepted values, see the [Reference](/planningboard/reference/index) section.
</Tip>

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

  * Swimlane Assignment Types
  * Planningboard Widget Parameters
  * Planningboard interface & basic interactions

  **Support Tickets**

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

  **Source Code**

  * `Config.java`
  * `PlanningBoardWidgetDependenciesProcessor.java`
  * `licenseReadonly.cy.ts`
  * `PlanningBoardWidgetRenderer.java`
  * `PlanningBoardDataService.java`
</Accordion>