> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Comment-Based Reviews

> Enable comment-based reviews in Nextedy RISKSHEET so that reviewers can add feedback directly as Siemens Polarion ALM comments on risk items, with no additional work item types required.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Prerequisites

* Risksheet installed and configured in your Polarion project
* Access to the sheet configuration for the target document (see [Find Configuration Files](/risksheet/guides/configuration/finding-config-files))
* Users with comment creation permissions on the target work items

## How Comment-Based Reviews Work

Comment-based reviews use standard Polarion work item comments as the review mechanism. When a reviewer adds a review through Risksheet, it creates a regular Polarion comment on the underlying work item. Each review displays the author name, timestamp, optional title, and formatted content.

Because reviews are stored as native Polarion comments, all review data lives in Polarion — Risksheet does not maintain a separate review store. Reviews are subject to standard Polarion authorization and audit infrastructure.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/yWl5nA2D0IzEnZC1/risksheet/diagrams/guides/reviews/comment-based-reviews/diagram-1.svg?fit=max&auto=format&n=yWl5nA2D0IzEnZC1&q=85&s=fa3a5c20cef6b9d6f6611234a71c291b" alt="diagram" style={{ maxWidth: "540px", width: "100%" }} width="540" height="240" data-path="risksheet/diagrams/guides/reviews/comment-based-reviews/diagram-1.svg" />
</Frame>

<Steps>
  <Step title="Enable Comment-Based Reviews">
    Open the sheet configuration for your document in the configuration editor (which supports YAML editing) and add the `reviews` section with `reviewManager` set to `CommentBased`:

    ```yaml theme={null}
    reviews:
      reviewManager: CommentBased
    ```

    That is the only required configuration property. No additional settings are needed for comment-based reviews.

    <Warning title="Only one review mode at a time">
      Risksheet supports three mutually exclusive review strategies: `CommentBased`, `WorkItemBased`, and `ApprovalBased`. If multiple modes are configured, `CommentBased` takes the highest precedence, followed by `WorkItemBased`, then `ApprovalBased`. Configure only one `reviewManager` value to avoid confusion.
    </Warning>

    <Note title="Approval review limitation">
      Risksheet approval review (`ApprovalBased`) creates approval-tagged comments but does not trigger Polarion's formal approval state transitions (draft → reviewed → approved). If you need full Polarion approval workflow integration, use Polarion's native approval features in addition to Risksheet reviews.
    </Note>
  </Step>

  <Step title="Toggle Review Columns in the Grid">
    Once comment-based reviews are configured, display the review columns in the grid:

    1. Open the Risksheet in your Polarion LiveDoc
    2. Use the review toggle command in the toolbar to show review columns
    3. Two system columns appear:
       * **Reviews column** — displays existing review comments for each risk item
       * **Add Review column** — provides the interface for creating new reviews

    Row heights automatically adjust when you toggle review columns to accommodate the review content.
  </Step>

  <Step title="Create a Review">
    To add a review on a risk item:

    1. Locate the risk item row in the grid
    2. Click the add review control in the **Add Review** column
    3. Enter a **title** (optional) and **review text** (required)
    4. Submit the review

    The review is saved as a standard Polarion comment on the underlying work item. Content is stored as plain text (not rich text).

    <Tip title="Reviews visible in Polarion too">
      Since comment-based reviews are standard Polarion comments, they appear in the Polarion work item detail view outside of Risksheet. This gives full visibility without locking review data inside the grid.
    </Tip>
  </Step>

  <Step title="View Existing Reviews">
    The Reviews column displays all active reviews for each risk item:

    | Field         | Description                                                                       |
    | ------------- | --------------------------------------------------------------------------------- |
    | **Author**    | Reviewer's full name from Polarion (falls back to user ID if name is unavailable) |
    | **Timestamp** | Creation date and time in `yyyy-MM-dd HH:mm` format                               |
    | **Title**     | Optional title displayed in bold (if provided during creation)                    |
    | **Content**   | Review text rendered as HTML                                                      |

    Reviews are displayed in chronological order. The system automatically filters out:

    * **Resolved comments** — comments marked as resolved in Polarion
    * **Unresolvable comments** — comments that cannot be loaded (e.g., from deleted users)
  </Step>

  <Step title="Customize Review Styling (Optional)">
    Review content is wrapped with the `risk_reviews` CSS class. You can customize the appearance by targeting this class in your Polarion CSS:

    ```css theme={null}
    .risk_reviews {
      font-size: 12px;
      line-height: 1.4;
      padding: 4px;
    }
    ```

    See [Configure Cell Styles](/risksheet/guides/styling/cell-styles) for more styling options.
  </Step>
</Steps>

## When to Use Comment-Based Reviews

| Advantage                                            | Limitation                                      |
| ---------------------------------------------------- | ----------------------------------------------- |
| Simplest setup — single configuration property       | Limited metadata per review                     |
| Reviews visible in Polarion's native comment history | No separate work item for tracking              |
| No additional work item types required               | Cannot query reviews independently via Polarion |
| Comments preserved in work item audit trail          | Plain text only (not rich text)                 |

Comment-based reviews are best suited for lightweight review feedback where formal approval workflows or independently queryable review records are not required.

If your process needs structured review records that can be queried, linked to other artifacts, or fed into traceability matrices, consider [Configure Work Item-Based Reviews](/risksheet/guides/reviews/workitem-based-reviews) instead.

## Troubleshooting

| Issue                                | Cause                                    | Solution                                                          |
| ------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------- |
| Reviews do not appear after creation | Browser cache or session issue           | Refresh the page and verify the comment exists in Polarion        |
| Cannot create reviews                | Insufficient permissions                 | Verify the user has comment creation permissions on the work item |
| Review shows user ID instead of name | Polarion user profile incomplete         | Update the reviewer's full name in Polarion user administration   |
| Review columns not visible           | Review toggle not activated              | Use the toolbar toggle to show review columns                     |
| Multiple review modes seem active    | More than one `reviewManager` configured | Confirm only one mode is set in the sheet configuration           |

## Verification

After completing configuration, you should see:

1. The review toggle available in the Risksheet toolbar
2. Reviews and Add Review columns appear when toggled on
3. New reviews created through the grid appear as comments in Polarion's work item detail view
4. Author names, timestamps, and content display correctly in the Reviews column

## See Also

* [Set Up Review Process](/risksheet/guides/reviews/setup-review-process) — overview of all review strategies
* [Configure Approval-Based Reviews](/risksheet/guides/reviews/approval-based-reviews) — approval-tagged comment reviews (note: does not trigger Polarion's formal approval workflow)
* [Configure Work Item-Based Reviews](/risksheet/guides/reviews/workitem-based-reviews) — reviews stored as separate linked work items
* [Manage Cross-Project Reviews](/risksheet/guides/reviews/cross-project-reviews) — reviews spanning multiple Polarion projects

<LastReviewed date="2026-06-08" />