Create reviews and review elements
Elements in a project change constantly. Therefore, reviews should be carried out regularly by specifically assigned persons. A review has the goal of checking the elements, such as requirements, for completeness and correctness. Reviews can also help to identify errors early on and avoid them in development.
Create a review
If, for example, requirements are completely defined, they should be proofread by one or more reviewers and checked for correctness, comprehensibility and completeness before they are passed on to development. You can create reviews for the following elements:
- test cases
- use cases
- element groups
If you want to review many elements, it is not necessary to create a review for each element. Instead, create an element group and assign a package to it.
- Select the element you want to review and choose Create Review.
- Give the review a unique name.
- To describe the review in more detail, select a review type and specify the deadline for the review.
- On the Description tab, specify what you want the review to achieve.
- On the Reviewers tab, use the Plus button to specify who is to participate in the review.
- If the review can start immediately, change the state to submit to review to signal that the reviewers can start immediately.
- Click OK to create the review. The review is created below the item.
Review an element
It is most convenient if you conduct reviews via queries. objectiF RPM provides by default the following queries:
- My Reviews
- Documents with reviews
- Requirements with reviews
- Element groups with reviews
- Use cases with reviews
Open a query by double-clicking it or using the Open context menu command. A review begins when the status changes from scheduled to ready for review. In this process, a revision is created both by the review itself and by the element that is to be checked. The change of state can take place in the review dialog or in a query. When the state of the review changes to ready for review, the state of the review comment also changes to ready. All assigned reviewers can start the review and enter their comments and remarks.
Record review comments
Each assigned reviewer can enter their comments on the review using the context menu command Record Review result. If a review does not go through the first time and must be repeated, the comments are not deleted, but remain visible.
- Open a review query. Alternatively, you can use the Products window to go to the item.
- From the context menu of the review, choose Record Review result.
- The comments are entered on the Comment tab. If comments from previous reviews have already been entered, you can view them on the Previous Comments tab.
- Confirm your changes with OK.
If all reviewers have agreed to the review, the review also changes to the accepted state and the review element automatically changes to the approved state.
As soon as a review is rejected, the review element must be revised. This is also signalled by a state change. If the review element has been reworked, the Definition complete event is triggered again. The review element then returns to the defined state and the review can be performed again.
Review and review element are in their original state again.
- From the context menu, select Enter Review Result.
- Enter your comments again on the Comment tab and select a state.
- Close with OK.
Show review comments
Findings, questions, positive or critical comments are recorded via review comments. In the tab Previous Comments the individual reviewer can see when he entered comments, what state he chose and what the last comments were.
If you want to know why it took so long to complete a review, open the history by selecting Edit Revisions / View History from the context menu. Here you can see how often the review was rejected, for example.
Notify reviewers via e-mail
In the state machine of reviews, you can define that all assigned reviewers are informed by e-mail that a review is due. As soon as the review changes to the defined state, an e-mail is sent that contains two links in the attachment. One link points to the review and the other to the review item.
Reviewers who return the review to the ready state do not receive an e-mail.
- Open the Settings by clicking the eye and then Show Settings.
- Expand the State Machine package and double-click …for Review.
- Select the Edit command from the context menu of the ready state.
- Switch to the State Actions tab and select the Notify assigned project staff action under Available State Actions by clicking the Plus button behind the action.
- Click on the three blue dots and select Review Comments.Reviewer from the list.
You can also customize the content of the e-mail.
Click on the blue Default text entry.
You will find a number of placeholders and properties that you can use in the e-mail. If you do not configure anything, the default text is used, which looks like this:
The attached links both lead to the application. The first link allows you to enter your comments directly. The second link opens the review item.
Ready to review
If the state of the review changes to ready for review, the state of the review comment also changes to ready.
A review’s state machine defines that a review is only completed and changed to accepted when all reviewers select the Accept event in the Record Review result dialog. If only one person selects the Reject state, the entire review changes to the rejected state.
As soon as a review reaches the rejected state, the review element also changes back to its original state definition ongoing. The review element is checked and is defined again in its original state at some point. The review can be edited again and is transferred to the state review ongoing.
If a reviewer cannot or does not want to judge a retouch, he has the possibility to trigger the Skip event on his review comment. With this he behaves “neutrally”. This means: if all other review comments are set to Accept, the review also changes to accepted.
If the review is already in the ready state and you notice that changes have to be made to the review element afterwards, the event Retouch can be triggered for the review element. This returns the review element to its definition ongoing state. The corresponding reviews and review comments are automatically transferred to planned.