Reviews

A review is a set of artifacts that you create to be reviewed by specific team members. The review follows a lifecycle that changes as participants complete the review.

You can create a review for individual artifacts that you select or you can create a review of a collection.

You create a review for individual artifacts by clicking on the Create Review icon in the Reviews section of the sidebar. After providing a name for the review, you then add artifacts and participants to the review by clicking on the appropriate buttons in the Review Editor and then clicking the Start Review button. E-mail notifications are automatically sent to participants when a review is started and whenever certain events occur in the review. Participants join the review by clicking on the review name, which appears in each participant's dashboard.

There are two kinds of reviews: a Formal review and an Informal review.

When you add a participant to a review, you assign a role to the participant that determines the actions that are required to complete the review. The following table describes these roles and actions.

Table 1. Reviewer role and required action
Participant Role Required Action
Approver This participant must either approve ( icon), disapprove (icon), or abstain (icon) for each artifact in the review before the review can move to the Reviewed or the Finalized state. Note that the icon that corresponds with the participant's choice appears in the status column in the review editor windows.
Reviewer This participant must either review an artifact (reviewed icon) or abstain (icon) from reviewing the artifact before the review can move to the Reviewed or Finalized state.
Optional This participant can optionally review or abstain from reviewing an artifact; however, the review can move to the Reviewed or Finalized state regardless of what this participant does.

Lifecycle Review States

The state of the review changes based on its level of completeness. The following is the main order in which a review goes through in its lifecycle:

Draft > In Progress > Reviewed > Finalized

The following table describes the life cycle states for a review:
Table 2. Lifecycle Review States
Review States Description
Draft The initial state of a review in which the creator of the review assigns a due date, adds review instructions, adds participants, assigns roles to participants, and adds artifacts to the review. Participants are not notified when the review is in the draft state.
In Progress When the creator of the review clicks the Start Review button, the review moves to the In Progress state. Participants join the review by clicking on the review title, which appears in their dashboards. When all participants have finished reviewing the artifacts, the review moves to the Reviewed state.
Paused An interim state in which the review has been paused. This state enables the creator of the review to change the participants, their roles, or the artifacts that comprise the review. In a Formal review, the creator can also elect to get the latest version of the artifacts, in which case all artifacts that were initially captured in the review are replaced with the latest versions of the artifacts. Note that participants cannot add review comments or mark artifacts as reviewed when the review is paused. The creator of the review must click the Continue button to resume the review.
Reviewed Reviewers have added comments to the artifacts and have clicked the Done button on their review. The creator of the review (or an administrator) can still make changes to the review at this point by pausing the review and making changes.
Finalized All necessary reviewers have completed the review and the creator has clicked the Finalize Review button. The review is saved and can no longer be modified. In the case of a Formal review, those specific versions of the artifacts that were approved are also saved. You can now create a collection containing the reviewed artifacts to continue working with these artifacts outside of the review.

Review Editor Sections

When a participant opens a review, the review editor appears with two collapsible sections: the Participant Review and the Overall Review. Participants can switch between the two sections by clicking either the participant review arrow (participant arrow) or the overall review arrow (overall arrow) (or by clicking in the section headers)

In the Participant Review, the participant sees the participant role and the artifacts that comprise the review. The participant views an artifact by double clicking on it, which displays the artifact in read only mode. Then, depending on the role assigned to the participant, the participant either approves, marks as reviewed, disapproves or abstains.

In the Overall Review, the participant sees the artifacts and the participants that comprise the review, but only the creator of the review (or an administrator) can make changes to the review. The creator of the review can change the review by clicking pause and then making changes. The creator can change the participants, their roles, or the artifacts that comprise the review. The creator can even replace the current version of the artifacts in the review with the latest version of the artifacts in the project.

E-mail Notification

You can manually add comments to a review in the Review editor sidebar; however, most events automatically generate e-mail notification to review participants.
Note: If e-mail was not configured when the product was first installed, you must first configure e-mail settings on the server to enable automatic e-mail notifications.
The following table provides a description of the events that cause e-mail notifications to be sent.
Table 3. E-mail Notification Events
Notification Recipient Events that cause e-mail notifications to be sent
All Participants When the review is started or when there are additions or changes to certain properties, such as due date, status and review instructions .
All Participants Artifacts are added to or removed from the review
Specific Participants Participants are added to or removed from the review.
Specific Participants Change to their status or to an artifact status that affects them. This event occurs when the creator of the review resets the participant status.
Specific Participant Reviewer role changes.

Reviewing a collection.

In addition to creating a review for individual artifacts, you can also create a review for a collection. You create a review of a collection from within the collection editor or from the collection context menu. When creating a review of a collection, you should note the following:

Feedback