Add parallel approvals in a state
- Robert Alexander Marshall
Overview
You can add multiple reviews in a single content review state, assign different reviewers, set the minimum number of reviewers for each review, and also add dependencies between reviews.
Parallel reviews
To add multiple reviews, put more than one approval macro into a state macro body.
For example, to create three reviews Grammar, Design, and Technical, the following markup is used:
{workflow:name=Parallel review}
{state:Editing|submit=Sign-off Review}
{state}
{state:Sign-off Review|approved=Published|rejected=Editing}
{approval:Technical}
{approval:Grammar}
{approval:Design}
{state}
{state:Published}
{state}
{workflow}This can also be done in the workflow builder.
The initial order of the reviews in the workflow popup on the page is the order in which the approval macros have been defined in the state.
Each of these reviews can be done in parallel; currently, with no pre-assignment of reviewers and no minimum number of approvals set, only one reviewer is required to complete each one.
As soon as all the reviews agree to Approve or Reject, the transition to the relevant workflow state will occur.
Reviewer settings
Each of the approval macros can use all the same features you'd expect from a basic content review. So, let's add some additional requirements on who can review and how many reviewers are required:
{workflow:name=Parallel review}
{state:Editing|submit=Sign-off Review}
{state}
{state:Sign-off Review|approved=Published|rejected=Editing}
{approval:Technical|user=&adam,matilde,suni}
{approval:Grammar|group=project-quality-leads|minimum=2}
{approval:Design|assignable=true}
{state}
{state:Published}
{state}
{workflow}Grammar review - reviewer settings
We've used the group parameter to limit the Grammar review to members of the project-quality-leads Confluence user group.
We've used the minimum parameter (Minimum approvals in workflowbuilder) to indicate that at least 2 people from this group are required to complete the review.
The Approve and Reject buttons are disabled for users who are not members of the project-quality-leads Confluence user group.
What happens if the transition has not yet taken place and a user who is a member of the project-quality-leads Confluence user group chooses to Reject the content?
Any previous reviewer Approve decisions are removed, and the popup only displays the Reject decision.
The Design review has been reset except for the new reject decision. The Reject decision can be by any user who is a member of project-quality-leads including those who have not yet undertaken the review.
The Approve and Reject decisions are recorded in the page activity report.
Technical review - reviewer settings
For the Technical review, we've used the user parameter to name three individuals who are allowed to perform that review.
The addition of the & operator before the first user in the list means that all the listed users are required to undertake the review. This adds the user avatars to the workflow popup.
If the & operator is not present and there are no other settings, only one of them would need to complete the review, but any of them could still review the content if they wanted to. Note that as the reviewers are not mandated to undertake the review (as the & operator is not present) the popup will not display the user avatars.
Design review - reviewer settings
For the Design review, we've used the assignable=true parameter to allow any Confluence user (members of the confluence-users user group) to be added to the review.
As you can see, the + Add reviewer link is added next to the Approve/Reject buttons.
Review dependencies and sequencing the reviews
There is often an order in which reviews must be performed, either due to process or compliance reasons or simply to minimize reviewer workload. For example, you might want to delay the Design review until the Technical review is complete, as any technical errors in the content would likely need fixing prior to the Design review.
To achieve this, we can add the hasapproval condition to the Design approval, like so:
{workflow:name=Parallel review}
{state:Editing|submit=Sign-off Review}
{state}
{state:Sign-off Review|approved=Published|rejected=Editing}
{approval:Technical|user=&adam,matilde,suni}
{approval:Grammar|group=project-quality-leads|minimum=2}
{approval:Design|assignable=true|hasapproval=Technical}
{state}
{state:Published}
{state}
{workflow}
Now, if someone selects the Design review prior to the Technical review being completed, they'll see the Approve/Reject buttons are disabled:
However, the ability to add reviewers is still available so you don't have to wait for the Technical review to finish to specify who should participate in the Design review.
Review display order
Reviews will be listed based on the order of the approval macros in your workflow markup, even if some reviews are dependent on other reviews (our Design review is dependent on the Technical review). Assigning a reviewer has no effect on the display order:
See also