Skip to main content
This page explains why review workflows exist as a first-class concept in Nextedy RISKSHEET, the three review strategies the product supports, where each strategy stores its evidence, and the limits you should know about before choosing one. It is conceptual; for the practical steps of turning a strategy on, see the Review Management guides.

​
Why Reviews Live in the Grid

In sectors governed by ISO 26262, ISO 14971, IEC 61508, and ISO/SAE 21434, risk analyses are formal records. A failure mode without evidence of independent review is, for an auditor, an unreviewed claim. Without an integrated mechanism, teams typically fall back on three patterns, all of which create gaps:
  • Exporting the risk table to a spreadsheet, circulating it for review, and manually reconciling redlines back into Polarion.
  • Opening each risk item individually in Polarion to add a comment or approval, losing the grid context that explains why the row matters.
  • Running a parallel document-level review that has no link to the row-by-row evidence inside the analysis.
Risksheet closes that gap by treating reviews as data on the same work items the grid already shows. Reviewers see a row in its hierarchical context, with its severity and occurrence values, its upstream requirement, and its downstream mitigation, and capture their judgement in place. The evidence is then queryable, filterable, and exportable using the same Polarion infrastructure as the risks themselves.
Risksheet does not maintain a separate review database. Every review — whether a comment, a linked work item, or an approval comment — is stored inside Polarion, subject to Polarion authorization, and tracked by Polarion’s audit infrastructure. Risksheet visualizes and edits this data; it does not duplicate it.

​
The Three Review Strategies

Risksheet supports three mutually exclusive review strategies, configured per document through the reviews.reviewManager property in the sheet configuration. The system inspects this value and routes all review operations — listing existing reviews, creating new ones, deciding whether the review columns appear at all — to the matching implementation. You pick one strategy per document; you do not mix two. The three strategies differ in where the review evidence is persisted and what shape it takes:
diagram
When reviews.reviewManager is configured, Risksheet enables two grid columns: one that lists existing reviews on each row, and one that lets reviewers add a new review with a title and text. Toggling these columns visible or hidden is a single user action; when toggled, Risksheet auto-sizes the affected rows so longer review entries do not clip. If no review manager is configured, neither column appears — the feature is invisible.

​
Comment-Based Review

A comment-based review is the lightweight option. Each review is stored as a Polarion comment attached to the reviewed work item. The reviewer types a title and a body in the grid; Risksheet creates a comment on the underlying work item; the comment then shows up everywhere Polarion shows comments — in the work item pane, in notifications, in mention queries, and back in the Risksheet grid. The mental model: think of comment-based review as a sticky note attached to the risk row. It is easy to start, easy to read, and easy to ignore. There is no separate object to track and no extra workflow state to maintain. The trade-off is that comments have a relatively flat lifecycle. They can be marked resolved or unresolvable, but they do not pass through review stages, do not carry their own custom fields, and cannot be queried in the rich ways work items can. Comment-based review fits early-phase analyses, peer-review notes during authoring, and processes where the formal sign-off happens at the document level rather than per row.

​
Work-Item-Based Review

A work-item-based review elevates each review to a full Polarion work item linked back to the reviewed risk. Choosing this strategy means every review carries the full weight of Polarion’s work item infrastructure: its own type, its own workflow, its own custom fields, and its own audit trail. Reviews can be queried, reported on, and assigned to specific reviewers the same way any other work item is. The mental model: think of work-item-based review as filing a review report, not pinning a sticky note. The report is itself an object — it has an ID, a status, an assignee — and it points back at the risk it reviewed via a bidirectional link. Configuration lives under reviews.typeProperties and supports the following properties:
  • itemTypes — the Polarion work item type used for each review (for example, review). Mandatory.
  • linkRole — the Polarion link role connecting each review to the risk it reviews (typically review). Mandatory.
  • query — an optional Lucene expression that further filters which linked work items count as reviews; useful when the same link role is reused for non-review purposes.
  • document — an optional target document, in SPACE/DOCUMENT form, where new reviews are created. When set, Risksheet creates reviews as positioned items inside that document, placing each new review after the last existing review item of the same type.
  • project — an optional target project ID, allowing reviews to live in a different project from the risk. Project resolution supports expression evaluation, so values like the current project can be referenced dynamically.
  • itemTemplate — an optional Velocity template for rendering each review in the grid. When omitted, Risksheet falls back to a default format that shows the review work item ID as a clickable link, the author’s full name (or user ID), the creation timestamp, the title if it differs from the description, and the HTML-rendered description.
Because the rendered output is wrapped in the risk_reviews CSS class, teams can style review entries to match their visual conventions. Work-item-based review fits formal validation workflows, sign-off processes that need their own reviewer assignment and status, and any context where review activity itself must be auditable as an artifact. It is the strategy of choice when an auditor will ask: “show me every review on this risk, who did it, when, and what state is it in”.
The work-item-based strategy requires both itemTypes and linkRole to be present. Missing either causes Risksheet to refuse review creation at runtime. The standard value for linkRole is review, and when document is configured it must be supplied in SPACE/DOCUMENT form (for example, Risks/HARA-2024). Always verify both required properties — and the format of document if you use it — before rolling out a configuration.

​
Approval-Based Review

Approval-based review uses Polarion’s native approval comment system. Each review is created as a Polarion comment tagged with the fixed title Approval comment, marking it as a sign-off rather than ordinary discussion. The grid lists existing approval comments — preferring the reviewer’s full name over their user ID, formatting the timestamp consistently, and hiding comments that have been resolved or are unresolvable so the active sign-off picture is always clear. The mental model: think of approval-based review as a stamp on the risk row. The stamp carries a name, a date, and a note. It is heavier than a freeform comment because it uses Polarion’s distinguished approval channel, and it sits naturally beside other approval evidence on the same work item.
Risksheet’s approval review creates approval-tagged comments but does not trigger Polarion’s formal approval state transitions (draft -> reviewed -> approved). Use this strategy when you want sign-off evidence captured next to other Polarion approvals, but do not assume that adding an approval review through Risksheet will move the work item through Polarion’s approval lifecycle. If the formal lifecycle matters, drive state transitions in Polarion separately.
This limitation is the most common misunderstanding in practice. Approval-based review is the right choice when your governance model treats the existence of approval comments as the evidence, not when it depends on the work item’s status field flipping to an approved state.

​
Selection Precedence

When multiple review manager values are technically configurable, Risksheet evaluates them in a fixed priority order: comment-based first, work-item-based second, approval-based third. In practice you should configure exactly one strategy per document; the precedence rule only matters in unusual situations where conflicting values exist. Treating reviews.reviewManager as a single-value property is the safe approach.

​
How Reviews Appear in the Grid

When a review manager is configured, two dedicated columns become available: one that lists the current reviews on each row, and one that lets a reviewer add a new review through a title-and-text input. Toggling these columns is a single command that hides or shows both at once and then automatically resizes affected rows to accommodate the typically taller content of review entries. If the configuration changes — for example, the review manager is removed — the columns disappear cleanly. The format the grid uses to display reviews depends on the strategy:
  • Comment-based shows each comment as it exists in Polarion.
  • Work-item-based shows either the default template (clickable ID, author, timestamp, title if distinct, HTML description) or whatever the configured itemTemplate produces.
  • Approval-based shows each approval comment with the reviewer’s name, timestamp, and comment body, filtered to active approval comments only.
In all three cases, the output is wrapped in a risk_reviews CSS class, so visual styling can be customized through the styles section of the sheet configuration.

​
What Risksheet Reviews Are Not

Several capabilities sit just outside Risksheet’s review feature today. Understanding the boundary prevents disappointment and helps you choose the right tool for the right step.
  • Risksheet review is not Polarion’s full work item approval workflow. Approval actions that move a work item through Polarion’s approval lifecycle — the formal draft -> reviewed -> approved transitions, with role-based approver lists, escalation, and notifications — are not exposed in the Risksheet grid today. This capability is planned but not yet available. Until it ships, teams that need full approval lifecycle integration drive those actions from the Polarion work item view or document view; Risksheet captures the discussion that informs the decision.
  • The Polarion resolution field is not editable from Risksheet. That field is typically mandatory during status transitions, and Polarion’s APIs do not allow third-party tools to drive transitions when mandatory fields are required. Use the Polarion work item view to change resolution or status.
  • Administrators can still see some fields as editable that Polarion otherwise treats as read-only. Polarion does not expose a complete read-only field contract to third-party products. When users with administrator permissions edit through Risksheet, the underlying Polarion check that would normally block the edit may not fire. Plan permission models accordingly; do not rely on Risksheet to enforce read-only state for administrators.
These constraints are real today. Treat them as design boundaries, not bugs.

​
Choosing a Strategy: A Decision Sketch

The decision is not which strategy is best in the abstract, but which one matches the artifact your process requires. If you cannot describe the artifact your auditor will ask for, that is a sign to step back and design the artifact before configuring the strategy.

​
Where to Go Next

For practical steps and configuration recipes, see the Review Management guides. For the underlying configuration property reference and the shape of reviews.typeProperties, see Configuration. To understand how reviews participate in Polarion authorization and visibility, see User Roles and Permissions and Data Model and Work Items (covers work item visibility and levels). For how reviews fit into the broader traceability picture between requirements, risks, and mitigations, see Traceability and Linking.
Last modified on July 10, 2026