Review Workflows

​

Why Structured Reviews Matter

In safety-critical development (ISO 26262, IEC 62304, DO-178C), risk analyses aren’t complete until they’ve been reviewed by qualified personnel. A safety manager must verify hazard classifications. A technical lead must approve mitigation strategies. A quality engineer must sign off before release. Without structured reviews, teams resort to email threads, meeting notes, or informal comments scattered across documents. This creates gaps:

• Accountability: Who actually approved this risk assessment?
• Traceability: When was the review completed?
• Completeness: Which items still need review?
• Audit evidence: Where’s the proof that reviews happened?

RISKSHEET’s review system addresses these gaps by embedding review workflows directly into the risk management interface.

​

Three Review Strategies

RISKSHEET supports three mutually exclusive review implementations, each matching different organizational workflows: You configure which strategy to use by setting reviews.reviewManager in your risksheet.json:

• "CommentBased" — Simplest option, reviews appear as comments
• "ApprovalBased" — Formal approvals with signature integration
• "WorkItemBased" — Reviews are independent work items with full lifecycle

The strategy you choose determines where review data lives, how it’s displayed, and what workflows are possible.

​

Comment-Based Reviews

The comment-based approach treats reviews as Polarion comments attached to risk work items. When a reviewer adds a review, RISKSHEET creates a comment with the review text. All existing comments on the work item appear in the review panel. When to use:

• Lightweight review processes without formal approval requirements
• Teams already using Polarion comments for collaboration
• Situations where review history should live with the work item

Characteristics:

• ✅ Simple configuration (no additional setup needed)
• ✅ Reviews visible in Polarion’s standard comment interface
• ✅ Email notifications follow Polarion comment settings
• ❌ No distinction between reviews and regular comments
• ❌ No formal approval states (approved/rejected)

Configuration: Set reviews.reviewManager to "CommentBased". No additional properties needed. Reviews are automatically rendered showing commenter name, timestamp, and text. See Configure Comment-Based Reviews.

​

Approval-Based Reviews

The approval-based approach integrates with Polarion’s native approval system. Reviews are approval comments with the special title “Approval comment”, distinguishing them from regular collaboration comments. When to use:

• Organizations already using Polarion’s approval workflows
• Compliance requirements for formal approvals with signatures
• Workflows where approval state (pending/approved/rejected) matters

Characteristics:

• ✅ Integrates with existing Polarion approval infrastructure
• ✅ Supports digital signatures (if configured in Polarion)
• ✅ Approval state visible in Polarion workflow
• ✅ Distinguishes formal approvals from casual comments
• ❌ Requires Polarion approval system configuration
• ❌ Only shows comments titled “Approval comment”

Configuration: Set reviews.reviewManager to "ApprovalBased". RISKSHEET filters for comments with title “Approval comment” and formats them with reviewer name (preferring full name over user ID), timestamp, and comment text. Resolved or unresolvable comments are automatically hidden. See Configure Approval-Based Reviews.

​

Work Item-Based Reviews

The work item-based approach creates reviews as separate Polarion work items (e.g., type “Review”) linked to the reviewed risk item. Each review is a full work item with its own lifecycle, status, assignee, and custom fields. When to use:

• Complex review workflows with multiple states (assigned → in-review → approved)
• Need to assign reviews to specific reviewers with due dates
• Want to track review progress in dashboards and reports
• Reviews need custom fields (review type, discipline, severity)

Characteristics:

• ✅ Full work item capabilities (status, workflow, custom fields)
• ✅ Reviews can be assigned to users and tracked separately
• ✅ Queryable for reporting (“show all pending reviews”)
• ✅ Can exist in different documents/projects than reviewed items
• ✅ Customizable display via HTML templates
• ❌ More complex configuration required
• ❌ Additional work item types and link roles needed

Configuration: Set reviews.reviewManager to "WorkItemBased" and provide a typeProperties object with link and query settings. See Configure Work Item-Based Reviews for the full configuration reference. Required properties:

• linkTypes — Work item type(s) for review items (e.g., “review”)
• linkRole — Link role connecting reviews to risk items (e.g., “reviews”)

Optional properties:

• query — Filter which reviews to display (e.g., exclude closed reviews)
• document — Where to load/create review items (e.g., “Reviews/SafetyReviews”)
• project — Which project contains review items (can differ from risk project)
• itemTemplate — Custom Velocity template for rendering review display

The itemTemplate receives $item (the review work item) and can render any fields. Default format shows work item ID (as hyperlink), author, creation date, title (if different from description), and description.

​

How Reviews Appear in RISKSHEET

Regardless of strategy, reviews are displayed in a dedicated review panel within the RISKSHEET interface. Users see:

• Reviewer identity (name or user ID)
• Timestamp (when the review was created)
• Review content (comment text, approval decision, or work item description)
• Status indicators (for work item-based reviews: assigned, in-progress, approved, etc.)

The review panel supports:

• Viewing existing reviews for the selected risk item
• Creating new reviews via a form (title and text)
• Filtering reviews (work item-based only: by status, reviewer, date range)

​

Creating New Reviews

When a user creates a review through RISKSHEET:

1. Comment-Based: A new comment is added to the risk work item with the review text
2. Approval-Based: A new approval comment titled “Approval comment” is created on the risk work item
3. Work Item-Based: A new work item of the configured review type is created, linked to the risk item via the configured link role, and optionally placed in the specified document

All strategies require the user to provide:

• Title (used as comment title or work item title)
• Text (the review content)

​

Review Workflow Patterns

​

Pattern 1: Simple Comment-Based Reviews

Scenario: Small team, informal review process, no compliance requirements. Configuration: Set reviews.reviewManager to "CommentBased" — no additional properties needed. Workflow:

1. Risk analyst creates FMEA entries
2. Safety engineer reviews items, adds comments via RISKSHEET review panel
3. Comments appear both in RISKSHEET and in Polarion’s comment interface
4. Email notifications sent per Polarion comment settings
5. Team discusses in comments until consensus reached

Limitation: No formal “approved” state. Approval is implicit (“no more comments” = approved).

​

Pattern 2: Formal Approval Workflow

Scenario: Regulated industry, digital signatures required, approval state must be tracked. Configuration: Set reviews.reviewManager to "ApprovalBased". Workflow:

1. Risk analyst creates HARA entries and marks them for review
2. Safety manager receives approval request (via Polarion approval workflow)
3. Safety manager reviews in RISKSHEET, adds approval comment
4. Polarion approval system tracks state transition (pending → approved)
5. Digital signature captured per Polarion configuration
6. Work items cannot proceed to next status until approved

Advantage: Leverages existing Polarion approval infrastructure and signature integration.

​

Pattern 3: Structured Review Items

Scenario: Large organization, multiple review types (technical, safety, quality), review tracking in dashboards. Configuration: Set reviews.reviewManager to "WorkItemBased" with typeProperties specifying multiple link types (e.g., safetyReview,technicalReview), a link role, and a status query to filter active reviews. Workflow:

1. Risk analyst creates failure mode entries
2. System automatically creates “SafetyReview” work items linked to high-severity failures
3. Reviews are assigned to safety engineers with due dates
4. Reviewers work through assigned reviews, updating status (assigned → in-review → approved)
5. Dashboard shows review progress: 15 pending, 8 in-review, 42 approved
6. Reports query for “risks with open reviews” to identify bottlenecks
7. Review work items can have custom fields: review type, discipline, findings severity

Advantage: Full visibility into review process, integration with project management tools, supports complex workflows.

​

Review Visibility and Permissions

RISKSHEET respects Polarion’s permission system for review operations:

• Viewing reviews: User must have read permission on the risk work item (and on review work items for work item-based strategy)
• Creating reviews: User must have permission to add comments (comment/approval-based) or create work items (work item-based)
• Modifying reviews: Comments/approvals can be edited per Polarion comment permissions; review work items follow standard work item permissions

​

Review Strategy Decision Guide

Rule of thumb:

• Use CommentBased for informal, lightweight reviews
• Use ApprovalBased when you need formal approvals and already use Polarion’s approval system
• Use WorkItemBased when reviews need full work item capabilities (status, assignment, reporting)

​

Common Misconceptions

​

”RISKSHEET Enforces Review Completion”

Reality: RISKSHEET displays reviews and provides the interface to create them, but it does not enforce review completion or block actions based on review state. Enforcement happens through Polarion workflows: configure work item status transitions to require approvals before allowing progression from “Draft” to “Released” status.

​

”All Three Strategies Can Be Used Simultaneously”

Reality: Review strategies are mutually exclusive. You configure one reviewManager value, and that determines how all reviews work for that RISKSHEET. Mixing strategies within a single sheet is not supported.

​

”Reviews Automatically Trigger When Risks Change”

Reality: Review creation is manual. Users explicitly create review entries through the RISKSHEET interface. Automatic review triggering requires custom Polarion workflows or scripts (e.g., “when risk severity changes to High, create a SafetyReview work item”). RISKSHEET provides the review interface but doesn’t implement automatic review logic.

​

Related Topics

• Implementation: Set Up Review Process
• Implementation: Configure Comment-Based Reviews
• Implementation: Configure Approval-Based Reviews
• Implementation: Configure Work Item-Based Reviews
• Advanced: Manage Cross-Project Reviews
• Concept: User Roles and Permissions
• Concept: Traceability and Linking
• Reference: Configuration Properties Index

Sources

KB Articles

• Setup risk review process

Support Tickets

• #6180

Source Code

• IReview.java
• AppConfig.ts
• risksheet.json
• SystemConsts.java
• WorkItemBasedReview.java