Tracker Item Review

This page demonstrates the process of performing a new Tracker Item Review.

The content of this page applies to codebeamer version 20.11-LTS (CARMEN) and up. For earlier codebeamer versions, see Start a new review - before 20.11.

• Reviews and
• Approvals

of (work) items in specific states without the need for an extra Approvals tracker and forking extra Approval tasks, as shown in Forking sub-processes from processes (work items).


This workflow-based review mechanism gives control over

• the specific (work) item states where reviews should be performed.
• the Reviewers (set of users that are exclusively allowed/qualified to review/approve the (work) item in that specific state).
• the Review configuration:
  • What type of electronic Signature (extra reviewer authentication) is required for submitting votes?
    • None - the user login is sufficient.
    • Password - the user must enter her/his password.
    • Username and Password - the user must enter her/his username and password.
  • in which function/role did a reviewer perform the review (optional, only since codebeamer 10.0)
  • how many approvals (positive votes) are necessary for the subject item to be considered successfully Reviewed/Approved?
    • what should be the designated status of approved (work) items?
  • how many rejections (negative votes) are allowed before the subject item should be considered Rejected/Declined?
    • what should be the designated status of rejected (work) items?

Application Configuration

  "review" : {
     "hideTrackerItemReview" : false
   }
 

See also: Application configuration

Review Configuration

To define a review state, select the Start a new review workflow action for the appropriate state (entry) or those incoming state transitions that should trigger the review.

For example: Configure an Approval for the status Waiting for approval of a (System/Customer) Requirements tracker:

As the approval process should start upon entering the Waiting for approval status, no matter via which transition, it is defined as a state entry action.

The Start a new review state can be invoked

• by selecting it form the On Entry drop-down list
• by clicking on it on the State Transition Diagram
  
• by clicking on More... selector ► State Entry
  
  
  
  Actions ► Start a new review
  

In the example, the Reviewers are chosen to be all users, referenced in the field Owner of the requirement to approve:

Make sure to grant Edit permission for the Owner field.

For the Review, it is configured that

• submitting votes requires the digital Signature of the reviewers, which is done by entering their Password.
• the reviewers should also be asked to specify in which Role they performed their reviews (only since codebeamer release 10.0).
• it requires all votes for the item to be considered approved, and
  • the designated target status for approved items should be Accepted.
• if more than 1 reviewer rejects the item, the item should be considered rejected, and
  • the designated target status, in this case, should be Draft.

The placeholder all stands for all actually assigned Reviewers including the allowed number of rejections.

If there are 3 reviewers, and the number of allowed rejects is 1, it actually requires 2 (positive) votes for the item to be approved.

In general:

• The number of allowed Rejects must be less than the number of Reviewers.
• The number of required Approvals is the least of
  • the specified number of votes.
  • the number of Reviewers minus the number of allowed Rejects (this is what all stands for)

A review started via Start a new review prevents the editing of the subject item as long as the review is in progress.

State transitions out of a review state can be associated with the current Review (result) via one of the special conditions:

• Subject approved
• Subject rejected

to only allow this transition if the review for the current item status was affirmative/positive or declined/negative.

Review Execution

With this example (System/Customer) Requirements tracker configuration in place, a requirements review can be started and executed.

When executing the Approve transition, the Approvers need to be specified in the Owner field.




In this example, all project members with Product Owner role are selected:






On the Reviews & Merge Requests tab of the resulting screen, a new review In Progress is listed.





The designated reviewers are project members having Product Owner role at the time the review was started.

None of the reviewers have reviewed the item yet.


If one of the designated reviewers takes a look at the item to review, a Review action is performed:





By clicking on Review, a popup dialog is displayed where the reviewer can

[Approve] or [Reject]

[Sign & Approve] or [Sign & Reject] the item.

If multiple Roles are configured for this review (only since codebeamer release 10.0), the user is asked to select the relevant Role to perform the review in.

Depending on the required type of electronic Signature (if any), the user may need to enter the Username and/or password for the submission.

For the signature generation process, see:Generating Electronic Signature with SSO Login

In this example, one of the reviewers rejects the requirement. Since the review allows one reject, this is not decisive yet.

Decisive approval:

As this is the decisive approval, the Reviewer gets the option to execute the state transition (in this case Accept) to the designated approved status (Accepted) directly.

With this, the review/approval process is completed.

Automatic Reviewer Role Setting

Since codebeamer release 21.09-LTS (EMMA), the automatic selection of the reviewer's appropriate role during a signing event is available.

To enabled this feature, apply the below Application configuration option:

"review" : {
"restrictRolesBasedOnFieldConfiguration" : true
}

Default value: false.

If set to true:

• the Reviewer's role is pre-selected on the review action dialog in case the field through which the reviewer is assigned to an item accepts one specific role only. The pre-selected role cannot be changed by the user.
  
  
• the Reviewer can choose from the restricted list of roles displayed on the review dialog in case the field through which the reviewer is assigned to an item accepts more than one roles.
  

The feature also works, with a slight difference, when performing a Mass review:

• The list of the selectable roles is computed based on all selected items. When a user is added to an item in a specific role, that role is displayed in the role selector list.
• In case the selected user role is not applicable to one of the items of the Mass review, an error message is displayed:
  

Mass review of selected items

Since codebeamer release 21.09-LTS (EMMA), a batch of multiple selected items can be reviewed at once. See Mass review.

Resolving stuck reviews

In case votes are missing from the designated reviewers for any reason and an item review gets stuck, users with Tracker Admin permission on the item's tracker can adjust the review configuration by clicking on the review Settings icon on the right of the review subject:





For example: Reduce the number of required votes.