> ## 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.
# Dependencies and Links
> In any project that contains more than a handful of work items, some items cannot start
***
## What a "link" is in Polarion
Polarion models every relationship between work items as a **link**, typed by a **link
role**. A link role is an identifier such as `depends_on`, `implements`, `parent`, or any
custom role your project defines. When you create a link between two work items in Polarion
(from the work-item form, from a document, or from inside Nextedy PLANNINGBOARD itself), you are
attaching a directed, typed relationship edge to both items in the Polarion data model.
Planningboard does not maintain its own relationship store. It reads the links that already
exist in Polarion and renders them visually on the board. This means:
* **Links are owned by Polarion**, not by the board. A link created on the board is
immediately visible in Polarion's work-item form, and vice versa.
* **Which links appear** on the board depends on which link roles you configure in the
widget parameter `PARAMETER_DEPENDENCY_LINK_ROLE`. Only the roles you specify are
visualized as dependencies.
* **Unrecognized link roles** are not shown on the board — not because the links are
broken, but because the board only renders the roles it is told to watch.
In Planningboard documentation, the word **link** refers to the raw Polarion relationship
data (any role). The word **dependency** refers specifically to a link whose role has been
designated for visualization via `PARAMETER_DEPENDENCY_LINK_ROLE`. The two terms overlap
in casual conversation, but the distinction matters when configuring the board.
***
## Two entry points for exploring links
Planningboard provides two distinct modes for seeing links, serving different planning
contexts.
### Card-level: Show Links
When you hover over any card, a quick-action icon appears in its upper-right corner. The
**Show Links** action (the chain icon) filters the board to show only the selected card and
the cards that are directly linked to it. All other cards are temporarily hidden.
This is a **focused, single-item lens**. It answers the question: "What is this specific
item connected to?" without altering any configuration. The view is transient — dismiss it
and the full board reappears.
You can also **add a link** from a card using the Add Link quick action (the second icon in
the hover menu). After clicking it, the same icon appears on all other cards. Clicking a
second card creates a link between the two. If the icon appears red on a card, a link
already exists — clicking it removes the connection instead.
### Board-level: Show Dependencies
The toolbar at the upper-left of the board contains a **Show Dependencies** toggle. When
activated, it overlays connection lines across the entire board, drawing a line between
every pair of cards that share a link role listed in `PARAMETER_DEPENDENCY_LINK_ROLE`.
**Show Dependencies** in the toolbar is only active when the widget parameter
`PARAMETER_DEPENDENCY_LINK_ROLE` has been configured. If no dependency link role is
set, the toolbar button has no effect. Configure the parameter in the widget's
**Work Items Dataset Configuration** section.
The board-level view answers a different question from the card-level view: "Given the
current distribution of work across Plans, where are the cross-Plan dependencies?" This
is most useful during release planning, when you need to spot cards in an early sprint that
block cards scheduled for a later sprint — a cross-Plan dependency that drag-and-drop
alone cannot reveal.
***
## How dependency lines are drawn
When Show Dependencies is active, Planningboard calculates a visual line between each pair
of linked cards that are currently visible on the board. The line connects the card
positions as they appear in the current grid — columns are Plans, rows are swimlanes.
A few properties of dependency rendering to keep in mind:
* **Only visible cards produce lines.** If a linked card is in a collapsed swimlane, or
filtered out of the current board view, its connection lines are not drawn. This means
dependency coverage is partial when the board is heavily filtered.
* **Lines are cosmetic, not enforced.** Planningboard draws the lines to inform your
decisions; it does not prevent you from moving cards in ways that violate dependency
order. Planning intent is yours to apply.
* **Direction follows the link role's directionality** as defined in Polarion. If a
`depends_on` role is configured as directed, the arrow points from the dependent item to
the item it depends on.
***
## Parent–child links and swimlane assignment
A special category of links is the **parent–child relationship**, used when swimlanes are
configured with the **Parent Item** assignment type. In this mode, each swimlane represents
a parent work item (for example, a Feature), and the cards inside it are child items (for
example, Tasks or Stories) linked to that parent via the configured **Parent Role** (such
as `implements`).
This introduces a constraint that distinguishes parent-mode swimlanes from other swimlane
types: when you drag a card, Planningboard resolves which parent that card belongs to via
its link, then places the card in the corresponding swimlane. You cannot drop a card into
an arbitrary parent row — the assignment follows the link, not the drop target.
If you drag a card toward the wrong parent swimlane, Planningboard will move it to the
correct parent row after the drop. This is not a bug — it is the board enforcing link
integrity in the Polarion data model. The card's parent link determines its swimlane
position.
The **Parent Query** parameter (optional) can filter which parent items appear as swimlanes,
letting you narrow the board to a relevant subset of the hierarchy without hiding the
child cards.
***
## Links created on the board vs. links managed in Polarion
When you add a link between two cards using the Add Link quick action, Planningboard writes
a Polarion link in the background. The board is simply a convenient interface for an
operation that could equally be performed in Polarion's work-item form.
From a planning perspective, this means:
* **Changes are immediately persistent.** There is no draft state — clicking the icon saves
the link to Polarion.
* **All Polarion link roles are available.** The Add Link action creates a link; the role
that Planningboard assigns depends on the `PARAMETER_DEPENDENCY_LINK_ROLE` configuration.
* **Deleting a link on the board removes it from Polarion.** Clicking the red icon on a
card that already has a link removes that link from the Polarion data model. This affects
all views that display the same relationship (Polarion's native work-item view, other
boards, reports).
***
## Verified items and link management
One important constraint applies to cards with the **Verified** status: they are locked and
cannot be moved or unplanned on the board. This lock extends to link operations — a
Verified card's position is treated as fixed from a planning perspective, even if its links
remain visible in Show Links or Show Dependencies mode.
Cards in **Verified** status cannot be dragged to a different Plan or swimlane, and
cannot be moved back to the Unplanned section. Plan around them, not through them.
***
## Mental model: the board as a link viewport
A useful way to think about Planningboard's dependency features is as a **viewport onto
Polarion's link graph**, filtered and arranged spatially by your planning dimensions (Plans
as columns, swimlanes as rows).
The full link graph exists in Polarion regardless of what the board shows. Planningboard
takes a slice of that graph — the work items matching your `query` parameter, arranged
across the Plans and swimlanes you have configured — and renders the edges within that
slice when you activate Show Dependencies.
This has two practical consequences:
1. **Board configuration shapes dependency visibility.** A narrow query or aggressive
swimlane filter may hide cards that are part of important dependency chains. Expanding
the view (broader query, fewer filters) reveals more of the graph.
2. **The board does not show you what it cannot see.** Dependencies that cross the boundary
of your current board configuration — items in other projects, items excluded by the
query, items in plans outside the `lastPlans`/`nextPlans` window — are silently absent.
They are real links in Polarion, but invisible on this board.
***
## Relationship to board structure concepts
Dependencies and links are one dimension of Planningboard's data model. They interact with
other structural concepts:
* **Board Structure** — the column/row grid that gives spatial meaning to where dependency
lines cross. See [Board Structure](/planningboard/concepts/board-structure).
* **Swimlane Assignment Modes** — particularly the Parent Item mode, which uses link roles
to define swimlane membership. See [Swimlane Assignment Modes](/planningboard/concepts/assignment-modes).
* **Prioritization** — item ordering within a Plan may interact with dependency order in
your process, though Planningboard does not enforce ordering constraints. See
[Prioritization](/planningboard/concepts/prioritization).
***
## Common misconceptions
**"Show Dependencies shows all links on the board."**
No — it shows only links whose roles match `PARAMETER_DEPENDENCY_LINK_ROLE`. If your items
have `parent`, `implements`, and `depends_on` links in Polarion, but only `depends_on` is
configured as the dependency role, only `depends_on` connections are drawn.
**"Adding a link on the board creates a board-local relationship."**
No — every link created via the Add Link quick action is written directly to Polarion and
is globally visible across all Polarion views, not just this board.
**"Dependency lines enforce scheduling constraints."**
No — the lines are visual aids. Planningboard does not prevent you from placing a card
in a Plan that conflicts with its dependency order. Enforcement is a process concern, not
a board constraint.
**"Collapsing a swimlane hides the dependency lines for those cards."**
Yes — collapsed swimlane cards are not rendered, so their dependency lines do not appear.
If you need to verify cross-swimlane dependencies, ensure the relevant swimlanes are
expanded.
***
## Further reading
* [Basic Board Interactions](/planningboard/getting-started/basic-interactions) — practical walkthrough
of the Show Links quick action and the Show Dependencies toolbar button.
* [Board Structure](/planningboard/concepts/board-structure) — how Plans (columns) and swimlanes (rows) define
the spatial layout that gives dependency lines their meaning.
* [Swimlane Assignment Modes](/planningboard/concepts/assignment-modes) — detailed explanation of the Parent
Item mode and how link roles drive swimlane assignment.
**KB Articles**
* Introduction to Planningboard
* Planningboard interface & basic interactions
* Swimlane Assignment Types
**Support Tickets**
* [#6681](https://support.nextedy.com/helpdesk/tickets/6681)
* [#6546](https://support.nextedy.com/helpdesk/tickets/6546)
* [#6777](https://support.nextedy.com/helpdesk/tickets/6777)
**Source Code**
* `AssignmentMode.java`
* `Config.java`
* `PlanningBoardWidget.java`
* `enum-rows-filter.cy.ts`
* `enum-rows-filter-folder-scope.cy.ts`