Skip to main content

​
Prerequisites

  • Risksheet installed and configured in your Polarion project
  • Access to the risksheet.json configuration file (see Find Configuration Files)
  • A Polarion work item type defined for review records (e.g., reviewItem)
  • A link role configured in Polarion for review relationships (e.g., reviews)

​
How Work Item-Based Reviews Work

When you select the work item-based review strategy, each review creates a new Polarion work item of the configured type. The review work item is linked to the reviewed risk item via a configurable link role. Links preserve the revision of the reviewed item for auditability. diagram

​
Step 1: Configure the Review Manager

Add the reviews section to your risksheet.json with the required properties: 
{
  "reviews": {
    "reviewManager": "WorkItemBased",
    "typeProperties": {
      "linkTypes": "reviewItem",
      "linkRole": "reviews"
    }
  }
}

​
Required Properties

PropertyDescription
reviewManagerMust be "WorkItemBased"
typeProperties.linkTypesThe Polarion work item type ID for review work items
typeProperties.linkRoleThe link role name connecting reviews to reviewed items
Missing typeProperties, linkTypes, or linkRole results in a runtime error when creating reviews. The error messages are: “TypeProperties for WorkItemBased reviews not set”, “LinkTypes for WorkItemBased reviews not set”, or “linkRole for WorkItemBased reviews not set”.

​
Optional Properties

PropertyDescriptionDefault
typeProperties.queryCustom query expression to filter retrieved reviewsNone (show all)
typeProperties.documentTarget document path for storing review work itemsSame document
typeProperties.projectTarget project ID for storing review work itemsSame project
typeProperties.itemTemplateCustom HTML template for review displayDefault format

​
Step 2: Configure Cross-Project Storage (Optional)

To store reviews in a dedicated document or different project, add the optional properties: 
{
  "reviews": {
    "reviewManager": "WorkItemBased",
    "typeProperties": {
      "linkTypes": "reviewItem",
      "linkRole": "reviews",
      "project": "QualityReviews",
      "document": "Reviews/RiskReviewLog",
      "query": "NOT status:closed"
    }
  }
}
When a target document is specified, new review work items are automatically positioned after the last existing review item of the same type in that document, maintaining chronological ordering.
The project and document properties support dynamic expression evaluation. This allows you to resolve target locations based on the context of the reviewed item.

​
Step 3: Customize Review Display (Optional)

By default, each review in the Reviews column shows:
  • Work item ID as a clickable hyperlink to the review work item
  • Author name (bold)
  • Creation date in yyyy-MM-dd HH:mm format
  • Title (if different from description)
  • Description rendered as HTML
You can override this format using the itemTemplate property: 
{
  "reviews": {
    "reviewManager": "WorkItemBased",
    "typeProperties": {
      "linkTypes": "reviewItem",
      "linkRole": "reviews",
      "itemTemplate": "<div class='custom-review'>...</div>"
    }
  }
}
Test custom item templates in a development environment before deploying. The template supports HTML with dynamic placeholders resolved at render time.
Reviews are wrapped with the risk_reviews CSS class, enabling additional styling through cell styles.

​
Step 4: Toggle Review Columns and Create Reviews

  1. Open the Risksheet in your Polarion LiveDoc
  2. Toggle review columns visible using the toolbar
  3. Locate the risk item you want to review
  4. Enter a review title and text in the Add Review column
  5. The system creates a new work item of the configured type, links it to the risk item, and displays it in the Reviews column
Each review work item is linked with a bidirectional relationship that preserves the revision of the reviewed item.

​
When to Use Work Item-Based Reviews

AdvantageLimitation
Full traceability via Polarion work itemsRequires additional work item type and link role setup
Reviews queryable and reportable independentlyMore complex configuration than comment-based
Supports cross-project review storageEach review creates a work item (volume consideration)
Custom display templates availableRequires Polarion admin to configure types and roles
Bidirectional links with revision tracking
Work item-based reviews are ideal for regulated environments where compliance standards require traceable, independently queryable review records.

​
Troubleshooting

IssueError MessageSolution
Missing type properties”TypeProperties for WorkItemBased reviews not set”Add typeProperties section with linkTypes and linkRole
Missing link types”LinkTypes for WorkItemBased reviews not set”Set typeProperties.linkTypes to a valid work item type ID
Missing link role”linkRole for WorkItemBased reviews not set”Set typeProperties.linkRole to a valid link role name
Reviews not appearingN/ACheck the query filter or verify document/project scope matches the review location

​
Verification

After completing configuration, you should now see:
  1. Review toggle available in the Risksheet toolbar
  2. New reviews create separate work items in Polarion of the configured type
  3. Bidirectional links between reviewed risk items and review work items
  4. Review work items visible both in the Risksheet Reviews column and in Polarion’s work item views
  5. If cross-project storage is configured, review work items appear in the target project/document

​
See Also

KB ArticlesSupport TicketsSource Code
  • WorkItemBasedReview.java
  • IReview.java
  • AppConfig.ts
  • SystemConsts.java
  • CommentBasedReview.java