Why Review Workflows Matter
Risk management in regulated industries is not just about identifying and scoring risks — it is equally about demonstrating that qualified personnel have reviewed, validated, and approved the analysis. Auditors and regulatory bodies expect traceable evidence of review activities. Without integrated review workflows, organizations typically fall back to one of these patterns:- Exporting risk tables to Excel, circulating for review via email, and manually reconciling feedback
- Navigating to each work item individually in Polarion to add comments or approvals
- Using separate document review workflows that are disconnected from the risk analysis grid
Three Review Strategies
Risksheet implements three mutually exclusive review strategies. You configure exactly one strategy per Risksheet document through thereviews.reviewManager property in risksheet.json. The system automatically detects which strategy is configured and routes all review operations to the appropriate implementation.
Comment-Based Review
Comment-based review is the simplest strategy. When enabled, reviews are created as standard Polarion comments attached to the work item being reviewed. Each review appears as a comment with the reviewer’s name, timestamp, and review text. How it works:- The reviewer opens the review column in Risksheet and enters review text
- Risksheet creates a Polarion comment on the underlying work item
- The comment is visible both in Risksheet’s review display and in Polarion’s native work item comment section
- Existing reviews are retrieved by reading comments from the work item
- Teams that want lightweight, informal review tracking
- Projects where review evidence does not need to follow a formal workflow with states
- Organizations that already use Polarion comments for collaboration and want review records in the same place
Work-Item-Based Review
Work-item-based review creates a separate Polarion work item for each review. These review work items are linked to the reviewed risk item through a configurable link role, creating a traceable relationship in Polarion’s work item graph. This approach is well suited to organizations that need review records to follow their own lifecycle and workflow. How it works:- The reviewer initiates a review from Risksheet, entering a title and description
- Risksheet creates a new work item of the configured review type
- A bidirectional link is established between the review work item and the reviewed risk item using the configured link role
- The link preserves the revision of the reviewed item, creating a snapshot of what was reviewed
- Reviews can optionally be created in a different project or within a specific Polarion document
- Organizations that need review records as first-class Polarion artifacts with their own workflows
- Projects where reviews must be tracked, assigned, and transitioned through states (draft, in-review, completed)
- Regulatory environments that require review records to be independently auditable work items
- Cross-project review scenarios where review records are stored centrally
| Property | Description |
|---|---|
reviews.reviewManager | Must be set to "WorkItemBased" |
reviews.typeProperties.linkTypes | The work item type used for review items |
reviews.typeProperties.linkRole | The link role name connecting reviews to reviewed items |
| Property | Description |
|---|---|
reviews.typeProperties.query | Custom query expression to filter displayed reviews |
reviews.typeProperties.document | Target document for review work items (supports expression evaluation) |
reviews.typeProperties.project | Target project for review work items (supports expression evaluation) |
reviews.typeProperties.itemTemplate | Custom HTML template for review display rendering |
project and document properties support dynamic expression evaluation, allowing the target to be determined at runtime based on context variables.
Document positioning: When reviews are created inside a Polarion document, they are automatically positioned after the last existing review item of the same type in the document structure. This maintains chronological ordering of review records within the document.
Custom rendering: By default, reviews display the work item ID (as a clickable hyperlink), author name, creation date, title, and HTML-rendered description. You can customize this display by providing an itemTemplate that defines custom HTML layout for review entries. All review content is wrapped in the risk_reviews CSS class for styling purposes.
Approval-Based Review
Approval-based review integrates with Polarion’s native approval comment system. Reviews are stored as approval comments on work items, leveraging Polarion’s built-in approval infrastructure. This approach provides the tightest integration with Polarion’s approval workflows. How it works:- The reviewer creates an approval review through Risksheet
- Risksheet creates an approval comment on the work item with the fixed title “Approval comment”
- The comment is stored using Polarion’s comment system with plain text format
- When displaying reviews, Risksheet retrieves all approval comments and renders them with reviewer name, timestamp (in
yyyy-MM-dd HH:mmformat), and comment text - Resolved and unresolvable comments are filtered out — only active approval comments are displayed
- Organizations that already use Polarion’s approval workflows and want review records to align with that system
- Projects where approval comments carry formal significance in regulatory documentation
- Teams that need approval evidence associated with specific work item revisions
Review Columns in the Grid
Risksheet uses two system columns to display and manage reviews within the grid:| Column | Binding | Purpose |
|---|---|---|
| Reviews | reviewsRendered | Displays existing review comments, status, and approval information for each work item |
| Add Review | reviewsAdd | Provides UI controls to create new reviews for the work item in the current row |
Review State and the reviewer Property
The reviewer configuration property (default: false) enables reviewer mode, which restricts the grid to review-specific interactions. When reviewer is set to true:
- Editing capabilities are restricted to review-related columns only
- Standard data editing is disabled, preventing reviewers from accidentally modifying risk values
- Review-specific UI controls are displayed in the grid toolbar
readonly property (which prevents all editing) — reviewer mode specifically permits review interactions while blocking data modifications.
How Reviews Integrate with Read-Only Behavior
Several Risksheet features interact with review workflows:| Feature | Effect on Reviews |
|---|---|
readonly: true | All editing disabled, including review creation |
reviewer: true | Only review-related editing permitted |
| Historical revision view | Grid becomes read-only; review creation disabled |
| Baseline comparison mode | Grid becomes read-only; existing reviews visible but new reviews cannot be added |
downstreamReadonly: true | Affects downstream items only; review columns on risk items remain functional |
Choosing the Right Strategy
The right review strategy depends on your regulatory environment, organizational processes, and how you need to manage review evidence.| Factor | Comment-Based | Work-Item-Based | Approval-Based |
|---|---|---|---|
| Setup complexity | Low — single property | Medium — requires type and link config | Low — single property |
| Review as Polarion artifact | Comment only | Full work item | Approval comment |
| Own workflow/lifecycle | No | Yes | No |
| Cross-project storage | No | Yes | No |
| Custom display template | No | Yes (via itemTemplate) | No |
| Integration with Polarion approvals | No | No | Yes |
| Formal audit trail | Basic | Full | Moderate |
Full work item approval workflow actions (transitioning work item status through approve/reject states directly from Risksheet) are not yet available in the current version. The review strategies documented above provide review commenting and approval commenting, but multi-role status transition workflows within the grid are planned for a future release. Currently, formal status-based approvals require navigating to the work item or document view in Polarion.
Interaction with Status Transitions
Risksheet supports limited status transitions for work items. However, status transitions that require mandatory fields (such as theresolution field) cannot be completed from within Risksheet. The resolution field specifically is not editable from the Risksheet grid because it is typically a mandatory field during Polarion status transitions. Status changes from Risksheet only succeed when all transition conditions are met without mandatory field requirements.
Administrators may be able to modify fields marked as read-only in Polarion when editing through Risksheet, because Polarion’s read-only field APIs are not fully available to third-party products. This is a known limitation — administrators should exercise caution when editing fields that Polarion marks as read-only.
Related Pages
- User Roles and Permissions — how user roles affect review capabilities
- Configuration System — how
reviewsfits into the overallrisksheet.jsonstructure - Data Model and Work Items — understanding work items, comments, and links in the Polarion data model
Sources
Sources
KB ArticlesSupport TicketsSource Code
IReview.javaAppConfig.tsrisksheet.jsonSystemConsts.javaWorkItemBasedReview.java