Skip to main content
Understanding how traceability works in Risksheet — and why it is designed the way it is — helps you build risk analysis structures that satisfy auditors, support impact analysis, and remain maintainable as your project evolves.

​
Why Traceability Matters in Risk Analysis

In a typical FMEA or HARA workflow, a risk item does not exist in isolation. It traces back to the requirement, safety goal, or system function that introduced the hazard, and it traces forward to the mitigation actions, test cases, or control measures that reduce the risk. Without these links, you cannot answer fundamental audit questions:
  • Which requirements are addressed by this risk assessment?
  • What mitigations have been implemented for this hazard?
  • If a requirement changes, which risk items need to be reassessed?
  • Is every identified hazard covered by at least one mitigation?
Risksheet addresses these questions by building traceability on top of Polarion’s native work item linking system. This means that links created in the Risksheet grid are not proprietary metadata locked inside a plugin — they are standard Polarion links, fully visible and navigable in the Polarion work item tracker, document views, and traceability reports.

​
How Linking Works

Risksheet uses Polarion work item links as its traceability mechanism. When you link a risk item to an upstream requirement or a downstream mitigation task, Risksheet creates a standard Polarion link with a configured role. The linking architecture supports three directions: diagram
  • Upstream links connect risk items to their source elements (requirements, safety goals, hazards, system functions) through itemLink and multiItemLink columns.
  • Downstream links connect risk items to mitigation actions, verification tasks, or control measures through taskLink columns.
  • Cross-item chains connect upstream items to each other through the nextedy.risksheet.upstreamChains property, creating indirect relationships via the common risk item.
Each link type is backed by a Polarion link role (for example, addresses, mitigates, verifies), which means the same relationships appear in Polarion’s built-in traceability matrix, impact analysis, and document comparison views.

​
Upstream Traceability

Upstream columns display work items linked to the risk item through a specified role. These links answer the question “what is this risk related to?” — for example, which requirement introduced the hazard, which system component is affected, or which safety goal this risk item supports. Risksheet supports two styles of upstream linking:
Link TypeColumn TypeUse Case
Single itemitemLinkOne-to-one relationships: one risk item traces to exactly one requirement
Multiple itemsmultiItemLinkOne-to-many relationships: one risk item traces to several safety goals or components
Single item links are simpler to configure and display a single work item ID or title in the cell. Multiple item links display an array of linked work items, allowing a risk item to trace back to multiple requirements, hazards, or safety goals simultaneously.

​
The Item Suggester

When creating or editing upstream links, Risksheet provides an autocomplete suggester that searches for matching work items. The suggester behavior is configurable at the project level:
SettingDefaultDescription
Fuzzy searchtrueMatches items even with slight spelling variations or typos
Wildcard searchtrueSupports * and ? wildcard characters in search queries
Result limit20Maximum number of suggestions displayed at once
Keyword mandatoryfalseWhether users must provide search keywords before results appear
All-field searchfalseSearches all fields of linked items instead of just primary fields
Enabling all-field search provides more comprehensive results but may impact performance in projects with thousands of work items. The default result limit of 20 balances usability with responsiveness — increase it only if users frequently cannot find items in the initial results.

​
Loading Upstream Items from Other Documents

Upstream items can reside in any Polarion document or project. The Risksheet loads them based on the link role and work item type configuration. This cross-document linking is fundamental to multi-level risk analysis architectures where, for example, system-level safety goals live in one document while component-level FMEAs live in another.
A common misconception is that Risksheet can automatically pre-populate the grid with all existing items of a given type from another document. This is not how it works. Risksheet always starts with an empty grid, and Risk Records (or your configured main work item type) must be created first. Upstream items are then linked to these records through the item suggester or other linking mechanisms.

​
Downstream Traceability

Downstream columns display mitigation tasks, control measures, or verification activities linked to the risk item. While upstream traceability answers “what causes this risk?”, downstream traceability answers “what are we doing about it?”

​
How Downstream Items Are Retrieved

The downstream trace provider retrieves linked work items using several filtering mechanisms applied in sequence:
  1. Role-based filtering — Tasks are retrieved based on the link role configured in dataTypes.task.role. If multiple roles are specified (comma-separated), the role filter is disabled and all linked items of the matching type are retrieved regardless of link role.
  2. Type-based filtering — Only work items matching the types configured in dataTypes.task.type appear as downstream items. This ensures that only relevant work item types (e.g., MitigationAction, VerificationTask) are shown.
  3. Custom query filtering — Additional Polarion queries can further filter which tasks appear. This is controlled by the nextedy.risksheet.applyQueryOnTasks property (default: true). Custom queries enable filtering by status, assignee, or other work item properties.
  4. Document-based loading — When loadTasksFromDocument is enabled, tasks are loaded from a specific document location rather than from work item links. This mode supports document-centric risk management workflows where tasks are organized in a separate document.

​
Sorting and Consistency

Downstream items are always sorted by local ID in ascending order (for example, TASK-1, TASK-2, TASK-10), regardless of the order in which links were created or retrieved. This provides predictable, consistent display across sessions and users.

​
Unresolvable Item Handling

The trace provider automatically excludes work items that cannot be resolved — items that have been deleted, moved to inaccessible projects, or are blocked by permission restrictions. The Risksheet silently filters these out, preventing broken references from appearing in the grid.

​
Upstream Chain Building

Some risk analysis methodologies require direct relationships between upstream items. For example, in an ISO 26262 HARA, you might need a direct link between a Harm and a Hazardous Situation, even though both are independently linked to the same Risk Record. The nextedy.risksheet.upstreamChains property enables automatic link creation between upstream items that share a common risk item. The format specifies a chain of fromType-linkRole-toType entries, comma-separated: 
harm-relatesTo-situation,situation-hasHazard-hazard
This configuration tells Risksheet: whenever a Risk Record has both a linked Harm and a linked Situation, automatically create a relatesTo link from the Harm to the Situation. Similarly, whenever a Situation and a Hazard are both linked to the same Risk Record, create a hasHazard link between them. diagram
The upstream chains feature only creates new links — it never deletes existing ones. If you remove an upstream item from a risk row, the chain link between previously connected upstream items remains intact. This is a safety measure to prevent accidental data loss, but it means you may need to manually clean up chain links if you restructure your risk analysis.

​
Revision-Based Traceability

Risksheet supports loading downstream items from specific document revisions or baselines, enabling historical traceability views. When viewing a historical revision, the system shows the tasks that were linked at that point in time, rather than the current state. The system uses either the work item revision or the document revision depending on configuration (isDownstreamFromRevision). This capability is essential for regulated environments where auditors need to verify the traceability state at a specific milestone or baseline — for example, confirming which mitigations were in place at the time of a design review. When changes are made to work items through Risksheet, Polarion’s suspect link mechanism can automatically mark related links as “suspect,” signaling that downstream or upstream items may need review. This behavior can be controlled:
  • Default behavior (auto-suspect enabled): Changes made in Risksheet trigger suspect link marking, following Polarion’s standard behavior.
  • Auto-suspect disabled (nextedy.risksheet.disableAutoSuspect set to true): Changes made in Risksheet do not trigger suspect links. This may be desired for certain workflows where bulk edits in the grid should not cascade suspect notifications.

​
Non-Risk Use Cases

Although designed for risk management, Risksheet’s traceability system is flexible enough for other use cases. The grid can be configured with any Polarion work item type as the main row item and any type as upstream or downstream. For example:
  • Requirements Traceability Matrix (RTM): Use Requirements as main items with Test Cases as downstream items, providing a structured view of test coverage
  • Functional Hazard Assessment (FHA): Use Functions as upstream items loaded from another document, with Failure Conditions created as downstream work items
Non-risk use cases require custom configuration of work item types in the dataTypes section. The exact configuration steps depend on your project’s work item types and link roles. Risksheet does not require specific fields or work item types — it is fully configurable for any traceability scenario.

​
Traceability in Exports

When exporting to PDF or Excel, traceability columns are included with appropriate formatting:
  • PDF export: Item links show the label property, multi-item links are rendered as comma-separated values, and server-rendered HTML is stripped to plain text. Downstream tables can be exported separately with deduplication logic.
  • Excel export: Item link columns export as plain text, multi-item link columns export as newline-separated lists, and server-rendered columns preserve list structure.
For practical configuration steps, see the how-to guides:
KB ArticlesSupport TicketsSource Code
  • DefaultTraceProvider.java
  • RisksheetProjectProperties.java
  • AppConfigParser.ts
  • ExportToPdf.ts