Creation and follow-up of a review

A user with the appropriate role can create a review and add reviewers among project members. Creating a review is done by clicking on the New Review button on the page listing the reviews of the project. A review can be also created from a template. To achieve this, click the toggle icon right of the "New Review" button then click "From review template".

Before being able to fill the review creation form, a configuration must be selected. Indeed, when a review is created, its own global configuration is created as well. A review global configuration can be found in the configuration picker, in the "Review Context" tab, or on the review details page. The review global configuration has no ties with the other global configurations of the project. Hence, the configuration selected in the review creation form serves to initialize the project administration settings to use in the context of the review. This way, the review global configuration does not start empty when opening the project administration pages. The configuration selected in the form is in no way used to assign the review's designs.

A review has a title, key, description, priority [High / Medium / Low], due date, as well as objectives. In addition, it can contain custom attributes, as setup in the project administration.

When creating a review from a template, the title and description of the review and its objectives are preset from the template's values.

The built-in priority attribute can be disabled with Disable the built-in priority attribute in reviews in the project administration's Settings page.

Disabling the priority in reviews also disables it for comments and findings.

Definition of contributors

Once the review has been created, you can list the contributors who will participate in the review:

1. On the Review page General tab, click the Edit button in the Contributors area.
2. Select among the members of the project those who can contribute to the review, or click the toggle to add contributors from a list of e-mails.

Defining review moderators

Once contributors have been added to the review, some of them can be assigned as review moderators. They can be either picked manually from the displayed table, or from a list of e-mails.
Being a review moderator means one can moderate everyone's comments and findings on the review, in compliance with the permission granted to the moderator on the project. For instance, a user can be added to review moderators, despite not having any role with the findings moderation permission. In that case, such a user will be able to moderate the review's comments, but not its findings.
In addition, even if a user has the required permissions to moderate comments and findings on a project, they will only be able to moderate them on reviews where they are assigned as a moderator.

Defining the scope of the review

You can then list the designs to review. For each design, you must tell which version (stream / baseline) is to be reviewed.

Here are the steps to narrow down the list of designs:

1. On the review page General tab, click the Edit button in the Designs area.
2. Select from the project designs those whose resources can be commented on as part of the review.
3. For each design, confirm or, if desired, update the selected configuration.

When the review is started, the data to review is frozen. If a design's configuration is a stream, a snapshot is automatically created, for use in the context of the review. At this point, the review keeps a reference both to the design's configuration that was initially added to the review, and also to the design's snapshot currently in review. This mechanism makes it possible to continue publishing new data on a design stream, without continuously impacting the review.

The "status of the reviewed version" column is illustrated with the icon. The icon indicates that the reviewed data is up to date, whereas the icon indicates that new data has been published on the design stream, and that the review does not include these updates yet.

Defining the objectives of the review

A review is broken down into review objectives. Each review objective is summarized by a title and a description.

Here are the steps to add a review objective:

1. On the review page Objectives tab, click the Add button.
2. On the General tab of the authoring window, give a title and description to the review objective. This information should tell a contributor what actions you expect from them.
3. On the Resources tab, select the primary resources affected by this review objective. The selectable resources are those contained in the designs referenced by the review, or the designs themselves.
4. On the Contributors tab, select the subset of contributors affected by this review objective. Not all review contributors are necessarily involved in each review objective. Reducing the number of contributors to this level makes it possible to assign to each contributor an objective according to their area of competence.

The review objectives can be reordered with the Sort button in the Review Objectives tab.

Monitoring of the review and life cycle

A review has a fixed workflow: [Creation of the review] => Not started => [Start the review] => In Progress => [Finalize the review] => Completed.

Once the review objectives are created, you can start the review by clicking the Start Review button on the toolbar. Contributors can then begin their review work and comment on design resources.

The review page details its progress:

• The Properties area displays the overall progress of the review.
• The Contributors area displays the progress per contributor, allowing you to know who to follow-up with if necessary.
• The Designs area displays the progress per design.
• The Review Objectives tab displays progress per review objective.

Once the contributors have completed their review, you can close the review by clicking the Close Review button on the toolbar. The review can then be re-opened, if necessary, via the same button.

Monitoring comments and findings

The Comments tab on the review page displays all results (comments and findings) created by contributors in this review.

Filtering comments

Results can be filtered by several criteria. Filtering allows multiple selection to refine the view. The following filters are available:

• Design: filter by specific design(s)
• Resource: filter by specific resource(s)
• Review objective: filter by review objective(s)
• Type: filter by content type (comments, findings)
• Status: filter by status (open, in progress, closed)
• Creator: filter by comment / finding author
• Group: filter by visibility group
• Resource attributes: filter according to configured custom attributes

For each filterable column, you can select multiple values via checkboxes, allowing you to combine filtering criteria. Only results matching the selected criteria are displayed.

Sorting comments

It is possible to sort results according to different criteria via the ... action button displayed when hovering over column headers:

• Resource:
  • By reading order (default): results are ordered according to the natural reading order of resources in the design
  • By ascending alphabetical order: alphabetical A-Z sorting of resource names
  • By descending alphabetical order: alphabetical Z-A sorting of resource names

  Note: When sorting alphabetically, resources are not grouped by design.

• Created on:
  • Recent content: the most recent results appear first
  • Older content: the older results appear first

The active sort is highlighted. You can reset the sort to return to the default sort (reading order of resources).

Setting up displayed columns

A user with an appropriate role can decide which resource attributes will appear in the table.

It is possible to hide most columns of the table to adapt the display to your needs. Four columns cannot be hidden as they are essential: Design, Resource, Unique key and Content. These columns appear grayed out in the configuration dialog box.

To hide or show columns:

• Individual hiding: use the ... action button when hovering over a column and select Hide column
• Global setup: click the blue Edit columns button located at the top left of the table. A dialog box opens, allowing you to transfer columns between two lists (displayed columns / hidden columns) to quickly configure the table display.

Locking the review

A review moderator can lock a started review by clicking the Lock review button at the top right of the banner.

Locking a review allows moderators to perform maintenance, export or cleanup operations without being impacted by contributor activity. A locked review prevents its contributors from commenting on designs in the context of the review's configuration, by graying out the Comment button in the right panel of the design.

Hovering over the grayed out Comment button displays this message "The review is locked. It is no longer possible to create comments. Please contact a review moderator." for clarity.

Locking constraints:

• Only review managers can lock and unlock a review
• Only managers can create, modify or delete comments and findings on a locked review
• A closed review cannot be locked or unlocked
• The locking/unlocking event is visible in the review audits

Locking information:

• A "Locked" property (Yes/No) is added to the review properties in the detail page
• The status of locked reviews appears as "In Progress (Locked)" in the review list and in the review audit (administration)
• A filter on the "Locked" state is available in the review audit page

Generation of a report on the review

Via the Report, button, a report document can be produced on the current review. For more information, see the section Generating a report.

Delete Review

A Delete drop-down menu is available on the review page for users with the appropriate permission. It permanently erases the review AND the comments created as part of this review.

Caution: As deletion is definitive, it is recommended that you use this feature only in rare cases.