A Review in codeBeamer is a snapshot of the items of a Tracker, a Release or a Report at a specific point in time. When a Requirement set is ready for approval you can start a new Review and let the contributors (reviewers and moderators) read each requirement specification and decide if it can be approved or needs more work. If a requirement gets updated while under review you may want to eventually restart the review, but at least you want to get notified about the change. The review feature of codeBeamer makes this process easy.
A Review in codeBeamer is a set of items. A review always contains a specific version of the items (depending on when the review was created). The contributors of the review can discuss the items being reviewed. After the discussion they have two choices for each item:
approve the item: the item is correct and sound, the reviewer found no problems
mark it as 'Needs More Work': the item is not yet fully developed or the reviewer found some problems
The review page makes the discussion and the approval/rejection easy.
There are two types of contributors for each review:
moderator: this type of contributor can edit, close and restart the review and also can add/remove contributors to it
reviewer: can approve or reject the items in the review and can add comments but cannot edit the review
A review can be closed and restarted by the moderator. A closed review is always read only meaning that none of the reviewers can review its items. A moderator can restart a closed review. Depending on the options set during the restart some items in the review can still be read only. The purpose of the restart is to incorporate the changes made on the items to the review. For this reason the restarted review references the versions of the items at the time of the restart.
Starting a Review
There are several ways of starting a review:
from the Review Hub: click on Review Hub on the toolbar and then click Create Review
from a Tracker: you can also start a review from a Tracker. In the more menu of the trackers you will find two menu items: Send to Review and Send Selection to Review. The first one creates a Review with each items in the tracker while second one creates a new Review from the selection (this works in table view and on document view). When creating a review from a whole tracker the review reflects the hierarchy of the original items (but this hierarchy is not updated when restarting the review).
from a Report: to create a Review with all the items currently returned by a report just go to the report page and click on the Send to Review link on the action bar.
from a Release: to create a Review with all the items that are currently assigned to a Release go to the release statistics page and in the more menu click on Send to Review. This also works on the KanBan board of a release with the extra of being able to filter the items sent to review.
Each of the methods described above will start a wizard with a few steps. If you start from the Review Hub first you have to select the source of the items to review.
In this step you can define the type of the review (tracker, report or release based review).
From the second step the wizard is the same for each review creation methods: a short summary about the selected items:
In the third step you can add the reviewers and the moderators of the review. You can also decide if you want the moderator to sign the review when closing it. All the things set up in this step can be modified later on the edit dialog on the review.
The last step of the review shows the setup of the review. If everything is correct click on the Create Review button. When the review is created you are redirected to the main page of the review.
Creating a review from baseline diff
You can easily create a review that contains only those items that changed or were added after a specific baseline. Note that this option is only available for tracker reviews that you start from the more menu of a tracker.
To create a review from baseline diff just click the Review only the items that have changed since the selected Baseline option in the first step of the review wizard (after selecting a baseline from the list).
The Review page
The review page has three sections. The left panel shows the items being reviewed in a tree structure. You can use this tree to navigate between the items just like on document view. On the second tab you can access the filters that you can use to show only the relevant items in the center panel.
The center panel shows the items in a document-like format and for each item displays the references in a box.
The right panel (which is closed by default) shows the properties, the review statistics and the comments of the selected item. Note that the property values on this panel reflect the state of the item at the time when the review was created. On the other hand, the comments section shows all the comments made on the item before the review was created and also the comments made on the review page.
Reviewing an item
To approve an item click on the tick icon before the item. To reject it click on the x icon. You can change your mind any time later (until the review is closed). You can also add a comment to the item by clicking on the bubble icon. Note that this will add a comment to the review not to the original item.
Note: in case you are rejecting an item, it is mandatory to add a comment to the item (from codeBeamer 9.3.0). If no comment is added, it is not possible to save the changes and close the review feedback window. If you are rejecting all review items at the same time, you only need to add one comment which will then be added to all items automatically.
Checking differences from the actual version
When an item in the review or one of its references is updated on the Head version the review page shows an orange badge after the item summary of above the references box. These are not only notifications but by clicking on them you can check the differences. Below is an example of the diff page. By default only the fields that were changed are listed.
There is an other type of notification badge that we show after a review was restarted. This badge is only shown if an item was updated while the previous version of the review was running. By clicking on this badge you can see the differences between the version included in the previous review and the version included in the current one.
On the left panel you can access the various filtering options of the review page:
All items: shows all items on the center panel
Items I have approved: show the items that were approved by the current user
Items need more work: shows the items that were marked as Needs More Work by the current user
Items I have reviewed: shows the items that were reviewed (either approved or rejected) by the current user
Items that I have not reviewed: shows the items that have not been reviewed by the current user yet
Items with my comment: shows the items that the current user commented
Items with comments: shows the items that were commented by any of the contributors of the review
Item updated since the review was created: shows the items that were updated (either the item itself or any of its references) since the current review started
The Relations section
If an item had references at the time of the creation of the review then these references are shown in a box under the item. Opening this box will load the references. If an item has updated references you will see an Updated References badge on this box.Hovering over the icon of the reference items will load the description of the item in an overlay. Clicking on the badges inside the relations section loads the diff page for the item.
You can export the current state of the review using the Export link on the action bar:
You can export to Word or Excel. For word export you have to option to export the comments. This will include in the exported document both the original tracker item comments and the comments added during the review.
When exporting a tracker to Word you have the option to include the latest review results in the exported document. Just check this checkbox on the export dialog:
With this option the exported document will contain a section with the review results for each tracker item that is in a review. An example:
The section starts with a short summary about the review and then lists the reviews of all reviewers on the item.
Starting from codeBeamer 9.4, you can add Groups and Project Roles to reviews as reviewers or moderators. All the project roles of the projects of the items involved in the review are selectable. When you add a role or a group, all the member users of that role or group can review/moderate the review (they will only see the review items where they have read access to the original item).
In the review editor, there is a tab called Manage Users. In this section, you can add and remove users, groups or roles from/to the review, and you can also replace reviewers. When replacing a reviewer in the review, the replacement user will get the replaced one's votes and can continue the review.
The review feedback page
You can access the feedback page by clicking on this icon on the toolbar:
The feedback page lists all the comments added to the items being reviewed before the review was created and also all the comments that were added on the review page. You can add new comments of different types and reply to previous comments.
The comment types currently available are Comment, Question, Problem and Proposed Change. These are marked with different colors on the feedback page. The comments and their replies are listed in hierarchical order the latest comment being the first. The comments added before the current review round was started are separated from the new ones.
The review statistics
To access the review statistics page, click on the third icon on the action menu bar:
The review statistics page shows some useful information about the current review:
The top segment shows some general information (who started the review and when, the deadline, if it is signed already and the baseline from which the review was created). The Overall Reviewer Statistics chart combines all the votes of all the reviewers.
The review result segment shows the progress of each reviewer.
The items segment summarizes for each item in the review the number of reviewers who approved, rejected or not yet reviewed the item.
Review statistics for individual items
You can check the review progress of individual tracker items at two places: on the item details page and on the right panel of the main review page (if an item is selected in the tree). Both places show the same information: all the reviews that the selected item is part of and the votes of each reviewers in that review.
Set Status mapping thresholds
From codeBeamer 9.4.0, you can set Status mapping thresholds by editing the Review. Check the Status threshold section of the Edit Review overlay:
The default values of the Approved and Needs more work fields are "All", which means that if all reviewers (who actually approved or rejected the item) voted the same, an automatic status mapping will be performed when finishing the Review.
If you uncheck the All checkbox, you can set any number as a value for these fields. When the review is finished, an automatic status mapping will be performed only if the number of the same votes (approved or rejected) reaches the set threshold number. For example, if you set 3 for the "Approved" status threshold, the item will be considered as "Approved" (and therefore, the automatic status mapping will be performed) only if at least 3 reviewers voted as "Approved" and there is no "Rejected" vote. In all other cases, the item will appear as "Mixed / Not Reviewed".
Finishing the review
A moderator can finish a review any time, doesn't necessarily have to wait until all the reviewers voted on each item. After finishing a review it becomes read only: nobody can review the items or edit the review.
To finish a review click on the Finish Review button on the action bar (this button is only available for moderators and only on running reviews). This will bring up an overlay with a short reviewer statistics. On this overlay you can finish the review or restart it immediately (see later).
On a finished review page none of the items are reviewable.
Finishing the review with status updates
This feature is not available for reviews that were created from a baseline.
When finishing a review, you can decide to update the status of the original items based on the result of the review. If there is a transition from the current status of the item and the status set on this page, then that transition will be executed with all the associated workflow actions. To get to the status setting page, click on Set Statuses on the finish review popup.
Clicking the button will bring you to the status setting page.
Here you will see the items grouped in two sections. The first section lists the items with mixed reviews. Mixed review means that the item got different review results from the different reviewers or it was not reviewed at all (or the number of the reviewers does not reach the set status thresholds). The second section lists all items that got only one type of review result (either approved or needs more work).
After each item, there is a list where you can select the status to set on the original item:
Do not change the status: the status of the original item will not change.
Set to "Mixed / Not reviewed" status: the original item will be set to the status selected in the Status to set for items that mixed or not reviewed list on the top of the page. This is the default option selected for items with mixed reviews, although, you can use the Do not change the status checkbox on the top of the page if you want that the status for all of the mixed / not reviewed items should not change.
Set to "Approved" status: the original item will be set to the status selected in the Status to set for approved items list on the top of the page.
Set to "Needs more work" status: the original item will be set to the status selected in the Status to set for items that need more work list on the top of the page.
From codeBeamer 9.4.0, if there is a transition from the current status of an item to the selected status, then the transition will be executed. It can happen that there are no transitions from the current status of the item to the selected status: these items will be highlighted. If you leave the Execute only valid transitions checkbox unchecked, the item statuses will still be updated without a valid transition. If the checkbox is checked, then because of the missing transition, the status will not be updated.
After you set up everything, click on the Finish Review button to execute the status updates.
Restarting the review
You can restart a finished review by clicking on the Restart Review link on the action bar of the review page. Restarting the review reopens some items for reviewing based on some criteria. You have several options to define which items to reopen:
Only not reviewed: reopens only those items that none of the reviewers reviewed (so it has no votes at all).
Only items that were updated or became suspected after starting the last review: by default, this option reopens the items that were updated after the review started. By checking the checkboxes below the option, you can also reopen the items that have updated downstream/upstream references.
All items that need more work: reopens all items about which at least one reviewer thinks that it needs more work.
All items in the current review: reopens all items in the review. If you check the Set all items as Not Reviewed option, then after restarting the review, all reviews will be cleared and all reviewers can start the reviewing process from scratch.
After restarting the review, the reopened items (based on the selected option) can be reviewed again: the previous votes can be updated. The items that do not match the criteria defined by the selected option are still read only. After restarting the review, the reopened items will reflect the latest version of the reviewed item. This way you can incorporate the changes made on the issues after the previous review round was started.
The Set as 'Needs More Work' all items not reviewed in the current review option will set all the items that were not reviewed by any of the reviewers as Needs more Work before restarting the review. Note that this change happens after the items that need to be reopened are selected. That is if you check the All items need more work option together, with this option, then only the items that were explicitly rejected by one of the reviewers will be reopened.
The Review Hub is always visible on the toolbar tab. This view is very similar to a table view. On this tab you can see all reviews that are accessible to you and also can create new reviews using the Create Review link.
Permissions and Licensing
To be able to use the Review feature:
you need a Reviews license
you have to be the member of a group that has the Enable Review permission (by default all groups got this permission but the system administrator can disable it)
To be able to see the items in a review:
you have to be either a moderator or a reviewer of the review (otherwise you won't see the review at all)
you have to have read permission to the items being reviewed. Although you can see the review without read permission on the reviewed items but you won't be able to see the item content and you won't be able to review the items
You can access the Review Hub in restricted mode if you have a Review Hub license. The restrictions if you have only Review Hub license:
you cannot open the right panel on the review page
you cannot be assigned to a review as moderator
you cannot edit, restart or finish the review
you are not able to check the differences from the Head version using the badges
you cannot export a review
you cannot check the review statistics page
With a review guard you can set some restrictions on the state transitions of a tracker. You can require that an item is reviewed before moving to a specific status. You can add a guard on the State Transitions tab of the tracker configuration page. Here you need to click on Edit from the context menu of a transition then on the Add link beside the Guard list.
After you set up the guard then codeBeamer will check if there is a finished review for the item on Review Hub whenever you want to execute the transition. The review must include a version of the item that was created when or after it was set in its current status.