> ## 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.
# Normalization
> **Normalization** is the mechanism by which Nextedy PLANNINGBOARD reconciles the relationship between a work item and the swimlane or Plan cell it belongs to when that assignment is computed — rather than sim
***
## The Core Problem: Derived vs. Stored Assignment
On a simple Kanban board, moving a card from one column to another is a direct write: the card's status field is updated and the card stays where you dropped it. Planningboard works differently for some swimlane modes because the swimlane a card appears in is **derived** from the card's field values — it is not an independent piece of board state.
Consider a board where swimlanes represent assignees. The swimlane a card appears in is determined by the work item's `assignee` field. If you drag the card to a different swimlane, Planningboard updates the `assignee` field on the underlying work item — the board then re-derives the swimlane from the updated field. The visible result is the same, but the mechanism matters: the board is always a read-consistent projection of your Polarion data, not a separate ordering layer.
Normalization is what happens during that re-derivation step. It ensures that after any change — a drag-and-drop, a field edit in Polarion, or a board refresh — each card ends up in exactly the swimlane(s) consistent with its field values.
***
## Assignment Modes and Normalization Behavior
Different swimlane assignment modes have different normalization behaviors because the underlying field types differ.
When `assignmentMode` is set to **Parent Item** (`PARENT`), plan cells mode (`planCellsMode`) is not supported. This means items assigned via parent links cannot participate in the stemming or SAFe plan-cell normalization described below. Use the **Users (Assignee)** (`ASSIGNEE`) or **Enumeration Field** (`ENUM`) modes if you need combined plan-and-swimlane normalization.
***
## Multi-Valued Fields: One Card in Many Swimlanes
A key aspect of normalization that surprises many users is what happens with multi-valued fields. When a work item has two assignees — say, Alice and Bob — Planningboard does not arbitrarily pick one swimlane. Instead, it displays the card in **both** Alice's row and Bob's row simultaneously.
This display is read-consistent: both instances of the card reflect the same Polarion work item. The board does not create duplicates — it creates multiple projections of a single record.
The same principle applies to multi-value enumeration fields. A work item tagged with two enum values (e.g. `team: alpha` and `team: beta`) appears in both swimlanes.
### The Not Assigned/Other Row
Planningboard always provides a **Not Assigned/Other** swimlane row for items that have no value in the grouping field. This row is the normalization target when you want to remove a value:
* Dragging a card from Alice's row to **Not Assigned/Other** removes Alice from the item's multi-user field — it does not clear all assignees. Bob remains.
* Dragging a card from the `alpha` enum lane to **Not Assigned/Other** removes the `alpha` value from the multi-enum field — other enum values remain.
When a work item appears in multiple swimlanes because of a multi-valued field, you remove one specific value by dragging the card from that value's row to the Not Assigned/Other row. The other values — and their corresponding swimlane appearances — are unaffected.
***
## Plan Cells Mode (planCellsMode)
Standard board mode assigns each card to a Plan (column) and a swimlane (row) independently. **Plan cells mode** (`planCellsMode`) introduces a tighter constraint: a card belongs to a specific *cell* — the intersection of a Plan column and a swimlane row — and the board enforces that pairing.
Plan cells mode is activated when using stemming-based planning or SAFe plan modes. In these modes, the Plan a work item belongs to and the resource (swimlane) it belongs to are encoded together — for example, in a resource field that pairs a team with a sprint. Normalization in this mode means the board reads that combined value, maps it to the correct cell, and places the card there. Moving the card to a different cell updates the combined value in Polarion accordingly.
When normalization is off, each team-iteration combination becomes its own column. The result is a wide board where Iteration 5 - Alpha, Iteration 5 - Beta, and Iteration 5 - Gamma appear as three separate columns even though they cover the same date range:
When normalization is enabled, same-numbered iterations across teams are merged into a single column. The board becomes a grid where each cell is a Team × Iteration combination:
The underlying Polarion plans share the same start and due dates (e.g. all Iteration 5 plans run Oct 20 – Nov 2, 2025), which is what allows the board to treat them as one column:
When you drag a card from one cell to another, Planningboard updates both the Plan assignment and the swimlane field. For example, dragging a card from the Alpha / Iteration 5 cell to the Gamma / Iteration 5 cell updates the work item's Team field from Alpha to Gamma, and the Plan assignment from Iteration 5 - Alpha to Iteration 5 - Gamma:
After the drag, the card moves to the Gamma row and the properties panel reflects the updated Team and Plan values:
The exact field format used to encode plan-resource pairs in stemming mode depends on your configuration. Consult the reference documentation for `stemming` and `planCellsMode` widget parameters for the encoding details applicable to your setup.
***
## Why a Card "Snaps Back"
A common source of confusion is dragging a card to a swimlane and seeing it immediately return to its original position. This happens because normalization re-derives swimlane membership from the work item's field value — and the field value was not (or could not be) updated by the drag.
The most common causes:
| Situation | Why it snaps back |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Parent Item** (`PARENT`) assignment mode | A card can only appear under its actual linked parent. Planningboard enforces the parent link; you cannot override it by dragging. |
| Read-only cross-project view | In cross-project views, the board may render as read-only. Drags are not persisted. |
| Multi-enum swimlane (field update fails) | If the field update fails server-side (e.g. due to a validation error), the board re-normalizes from the unchanged field value. |
| `showEmptySwimlanes = True` with no matching value | If you drag to a lane whose value does not exist on the item and the update is rejected, the card returns to its previous lane. |
When a card snaps back, Planningboard is telling you that the field update did not happen. Check the work item directly in Polarion to understand why the field value was not updated (workflow constraint, required field, permissions, or field type mismatch).
***
## Swimlane Sort Order and Normalization
One consequence of normalization worth understanding: **swimlane sort order is coupled to item sort order**. Because swimlanes are derived from field values rather than being independent objects with their own position, the vertical order of swimlanes on the board is controlled by the `swimlaneSort` parameter (e.g. `alphabetical`), not by dragging the swimlane headers themselves.
As of Planningboard 25.9.0, parent swimlanes can be sorted by any custom property, including priority. This applies to the **Parent Item** (`PARENT`) assignment mode and gives teams control over which parent swimlane appears first without altering the underlying work item structure.
***
## Normalization and Capacity
Capacity bars per swimlane are computed from the normalized state: the board sums capacity values for all cards in a swimlane as derived from the current field values. This has one important consequence for multi-valued fields — **a work item's capacity can be counted more than once** if it appears in multiple swimlanes.
For example, if WI-42 is assigned to both Alice and Bob and carries a `storyPoints = 5` capacity value, it contributes 5 points to Alice's capacity bar and 5 points to Bob's capacity bar.
There is no automatic capacity distribution across swimlanes for multi-valued fields. Each swimlane sees the full capacity of every card it contains. Teams using multi-user or multi-enum swimlanes should account for this double-counting when interpreting capacity bars.
For deeper discussion of capacity calculation and display, see [Capacity Tracking](/planningboard/concepts/capacity-tracking).
***
## Mental Model Summary
Think of Planningboard as a **live query view** over your Polarion work items, not a standalone board with its own card positions:
1. **The board's state is always derived from Polarion field values.** There is no separate "board position" stored independently.
2. **Drag-and-drop is a shortcut for a field update.** Moving a card changes the underlying field; normalization then re-renders the board from the updated data.
3. **Multi-valued fields produce multiple swimlane appearances.** This is correct and intentional — it reflects the item's actual field state.
4. **Snapping back means the field update did not happen.** The board is giving you accurate feedback about your Polarion data.
5. **Plan cells mode tightens the constraint.** Each card belongs to one cell, and moves update the combined plan-resource field.
***
## Related Concepts
* [Swimlane Assignment Modes](/planningboard/concepts/assignment-modes) — the full list of assignment modes and their configuration options
* [Capacity Tracking](/planningboard/concepts/capacity-tracking) — how capacity values are aggregated per swimlane and displayed
* [Plans Modes](/planningboard/concepts/plans-modes) — plan types (Project Plans, SAFe modes) and how they interact with plan cells normalization
* [Board Structure](/planningboard/concepts/board-structure) — the overall anatomy of the board (columns, rows, cards, sidebars)
**KB Articles**
* What is 'Normalization'
* Introduction to Planningboard
* Swimlane Assignment Types
**Support Tickets**
* [#6681](https://support.nextedy.com/helpdesk/tickets/6681)
* [#5879](https://support.nextedy.com/helpdesk/tickets/5879)
* [#6777](https://support.nextedy.com/helpdesk/tickets/6777)
**Source Code**
* `AssignmentMode.java`
* `Config.java`
* `enum-rows-filter.cy.ts`
* `PlanningBoardWidget.java`
* `enum-rows-filter-folder-scope.cy.ts`