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 asdepends_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 inPARAMETER_DEPENDENCY_LINK_ROLE.
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.
- 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_onrole 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 asimplements).
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.
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_ROLEconfiguration. - 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.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 yourquery 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:
- 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.
- 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/nextPlanswindow — 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.
- Swimlane Assignment Modes — particularly the Parent Item mode, which uses link roles to define swimlane membership. See Swimlane 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.
Common misconceptions
“Show Dependencies shows all links on the board.” No — it shows only links whose roles matchPARAMETER_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 — practical walkthrough of the Show Links quick action and the Show Dependencies toolbar button.
- Board Structure — how Plans (columns) and swimlanes (rows) define the spatial layout that gives dependency lines their meaning.
- Swimlane Assignment Modes — detailed explanation of the Parent Item mode and how link roles drive swimlane assignment.