Reviews

Edit online

You can create a review for specific team members to review artifacts, collections, or modules. The status of a review changes as participants complete the review. You can create a review from within a stream or a baseline.

You can generate reports about reviews and send email notifications to participants when reviews start and when certain events occur in a review. For instructions on how to create a review, see Creating reviews.

Remember: You can modify artifacts in a stream, but not in a baseline.

Reviews in a stream or baseline

When you create a review in an editable stream, the artifacts in the review can change. For example, if a team member edits the artifacts in the stream, those changes are reflected in the review. Therefore, you must create a review in a stream only if you know that the artifacts are not going to change significantly during the review.

If you have projects that are not enabled for configuration management, and you do not want the artifacts in a review to change, you must create the review from within a baseline.

If your project or organization requires validation of baselines, you can configure a project to require electronic signatures (e-signatures) on baselines. See Enabling Electronic signatures for a baseline for details on how to configure a baseline to require electronic signatures and Signing a baseline electronically for details on how to add an electronic signature to validate and sign a baseline.

Note: In projects enabled for configuration management, the baseline contains the artifacts in a component, not the project.

Tip: Reviews are visible on the Reviews page, regardless of the configuration (stream or baseline) you are currently working in. When you click a review, you automatically switch to the configuration in which the review was created.

Reviewer roles

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 the roles and actions.

Table 1. Reviewer role and required action
Reviewer role	Required action
Approver	Approvers must approve, disapprove, or abstain for each artifact in the review before the artifact can move to the reviewed or the finalized state. The icon that corresponds with an approver's choice is shown in the status column in the review editor window.
Reviewer	Reviewers must either review an artifact or abstain from reviewing it before the review can move to the reviewed or finalized state.
Optional reviewer	Optional reviewers can review or abstain from reviewing an artifact. However, their progress is not calculated in the overall progress of the review. The review can move to the reviewed or finalized state regardless of what optional reviewers do.

Lifecycle review states

The state of the review changes based on its level of completeness. Typically, a review moves through this order in its lifecycle:

Draft > In Progress > Reviewed > Finalized

This table describes the lifecycle states for a review.

Table 2. Lifecycle review states
Review state	Description
Draft	This state is the initial state of a review. 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 Start Review, the review moves to the in-progress state. Participants join the review by clicking the review title, which is shown on their dashboards. When all participants are finished reviewing the artifacts, the review moves to the reviewed state.
Paused	Paused is an interim state in which the review is paused. This state is useful when the creator of the review needs to change the participants, their roles, or the artifacts in the review. In a formal review, the creator can also get the latest version of the artifacts. In that case, all the artifacts that were initially captured in the review are replaced with the latest versions of the artifacts. When a review is paused, participants cannot add review comments or mark artifacts as reviewed. The creator of the review must click Continue Review to resume the review.
Reviewed	In this state of the review, the reviewers have added comments to the artifacts and clicked Done for their reviews. To continue the review, the creator of the review or a project administrator can change the review and then click Continue Review.
Overdue	A review request is overdue after 11:59 PM on its due date. At 12 midnight, the review is marked as overdue. This default setting cannot be modified.
Finalized	To reach this state, all the necessary reviewers must complete the review and the creator must click Finalize Review. The review is saved and can no longer be modified.

Review editor

When you open a review, the Review editor opens with two collapsible sections: Participant Review and Overall Review. You can switch between the two sections by clicking either section header.

In the Overall Review section, you can view the number of review comments for an artifact.

Reports and email notifications

To generate a document-style report about the details of the review, click the Generate a document-style report for this view icon in the header, and follow the prompts in the wizard.

You can manually add comments to a review in the Review editor sidebar. However, most events automatically send email notifications to review participants. If email was not configured when the product was first installed, you must first configure email settings on the server to enable automatic email notifications. For instructions, see Configuring email settings.

This table describes the events that cause email notifications to be sent.

Table 3. Email notification events
Notification recipient	Events that cause email notifications to be sent
All participants	A review that was in the Draft state starts for the first time.
All participants	Artifacts are added to or removed from the review.
Specific participants	Participants are added to or removed from the review.
Specific participants	Changes occur that affect the participants, the status of the participants, or the status of an artifact. This event occurs when the creator of the review resets the participant status.
Specific participant	The role of the participant changes.

Collection reviews

In addition to creating a review for individual artifacts, you can create a review for a collection. You create a review of a collection from within the collection editor or from the collection menu. When you create a review of a collection, remember this information:

You cannot add a collection to a review in the Review editor.
When you create a review of a collection, the review includes all the artifacts that are in the collection.
The list of artifacts in the review is defined by the collection. You cannot add or remove artifacts in the Review editor.
If the artifacts list in the collection is modified during the review, you can pause and then continue the review to get the latest list of artifacts.

Module reviews

You can add modules to a review. You cannot add artifacts in the module. However, you can add comments to the artifacts in the module. You can mark the module as approved or reviewed. You can use the Review Comments column for adding the review comments. You can view the Review Comments column and the associated review comments only when you are in a review.

If you want reviewers to review specific artifacts in the module (and not the entire module), you can define a view that identifies the artifacts to review. For example, you can show attributes or tags that identify what to review, or filter out artifacts that do not require review. To define this view, you must open the module from the review; otherwise, you cannot include the Review Comments column.