Overview
Content reviews are a crucial part of most workflows.
Often called "Approvals", they are characterised by a decision to Approve or Reject the content and, based on that decision, the workflow will generally transition to another state.
Defining reviews
One or more reviews can be added to a state using the {approval} macro:
{workflow:name=Reviews}
{state:In Progress|submit=Review}
{state}
{state:Review|approved=Approved|rejected=In Progress}
{approval:Technical Review|assignable=true}
{state}
{state:Approved}
{state}
{workflow}
The approved and rejected parameters on the {state} macro determine which states to transition to if the review is Approved or Rejected
Reviewers
The people who make decision to Approve or Reject are called Reviewers.
The settings of the {approval} macro determine who can review, or, if users are allowed to assign reviewers, who can be assigned.
All the reviewers must reach agreement before the review will be considered Approved or Rejected. You can use Events to change this behaviour, for example to facilitate Fast-tracked Rejections.
Multi-group reviews
In cases where more than one team of reviewers is required, just add more {approval} macros to the state.
Permissions
By default, a user must have Edit or Admin permissions in order to take part in a content review.
However, if the App configuration is set to allow anyone to view Workflow Activity and Drafts then users with View permission, so long as they are logged in to Confluence, will be able to take part in reviews (since version 4.6).
Credentials
Reviewers can optionally be required to verify their credentials before making a review.
See: Reviewer Authentication, Credentials prompt
Notifications
By default, assignees and page watchers will receive notifications about the review progress, and all interactions will be tracked in the Activity Report - Content.
Approval role
Use the optional approval role feature to record the roles that your approvers are performing. This is a more flexible method of capturing roles compared to named reviews, and allows you to easily assign ad hoc roles when necessary.
When creating a workflow using Workflow Builder, to use approval roles, open the advanced section of 'Edit approval' and tick 'Enable roles'
Roles can also be enabled in the {approval} macro by including the roles=true parameter.
Macros
-
approval macro — Add content-focussed reviews to states
-
approve-children macro — Approve approvals on child pages
-
approve-page macro — Approve an approval
-
reject-children macro — Reject approvals on child pages
-
reject-page macro — Reject an approval
Events
All aspects of the review process generate Events, which can be used to Trigger Actions.
Reviewer assignment events:
pageapprovalassignednewsapprovalassignedapprovalunassigned
Approval events:
pageapprovednewsapprovedpagerejectednewsrejected
App configuration
| Setting | Where | Notes |
|---|---|---|
| Workflow Activity and Drafts Visibility | Who can see the workflow and draft content? If set to Everyone, then View-only users can also participate in the review. | |
| Page Update Reset Approval | During an active review, if the content is updated should existing approvals be reset? | |
| Approval Comment | Should comments be mandatory when participating in a content review? | |
| Approval – Assignee | Should assigned reviewers receive email notifications about the content review? | |
.approval.minquery | Set how many characters must be typed when searching for reviewers |
Examples
-
Adding Multiple Reviews — Add multiple reviews to a content review, set assignee requirements and review dependencies, list ordering
-
-
-
Assignment Examples — Define who can take part in, or be assigned to, a content review.
-
Fast-tracked Rejections — How to require everyone to Approve, but only need one person to Reject
-
Make tasks disable a review — Use a Value Reference Condition to check that all tasks are complete. You need the Reporting for Confluence app in addition to Comala Workflows.
-
Reviewer Authentication — This example shows how to authenticate reviewers during a content review.
-
State expiry dates — Using state expiry dates, defining them with metadata, and making them editable
-
Workflow Report Macro - Approvals — Keep track of content reviews across multiple spaces.
-
Workflow Report Macro - Dashboard — Keep track of your tasks across multiple spaces.
