Reviews

Overview

Content reviews are a crucial part of most workflows.

Often called "Approvals", they are characterized 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:Draft|submit=Review}
   	{state}
   	{state:Review|approved=Approved|rejected=Draft}
      {approval:Technical Review|assignable=true}
   	{state}
	{state:Rejected}
	{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

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).

Reviewers

The people who make the decision to Approve or Reject are called reviewers.

The settings of the {approval} macro determine

if anyone can review
who can review
who must undertake the review (and is pre-assigned by the workflow on transition into the content review state)
if users are allowed to assign reviewers
and if the review is assignable you can limit who can be assigned

All assigned reviewers must reach the same decision (all be in agreement) before the review will be considered approved or rejected.

You can use Events to change this behavior, for example, to facilitate fast-tracked rejections.

Anyone can review

You can set the approval so that Anyone (with edit and view permission) can undertake the review.

A single reviewer decision will action the approved or rejected transition.

{state:Draft|approved=Approved|rejected=Rejected}
	{approval:Review}
{state}

Assignable review

The approval can be set to allow one or more users to be assigned to the review.

Once a user is assigned, only that user can undertake the review. But additional users can be assigned if the transition has not taken place.

If more than one user has been assigned, all users must agree for a transition to occur.

Users who have not yet undertaken a decision can be unassigned.

{state:Draft|approved=Approved|rejected=Rejected}
	{approval:Review|assignable=true}
{state}

Minimum reviewers

You can set a minimum number of reviewers to agree on the approved decision for the transition to occur.

A minimum can be required when the approval is set so

anyone can approve
the content review is assignable
reviewers are limited

{state:Draft|approved=Approved|rejected=Rejected}
	{approval:Review|minimum=3}
{state}

Limiting who can be assigned

You can also limit who can be assigned.

{state:Draft|approved=Approved|rejected=Rejected}
	{approval:Review|assignable=true|user=elle,suni|group=assigners}}
{state}

Limiting reviewers

You can also simply limit users who can review. Only these users will be able to undertake the review.

None of the users' avatars who can undertake the review are displayed in the workflow popup.

{state:Draft|approved=Approved|rejected=Rejected}
	{approval:Review|user=elle,suni|group=assigners}
{state}

All other users will simply see the Approved and Rejected options disabled (greyed out) in the workflow popup.

Requiring users to undertake a review

Reviewers can be mandated to undertake a review. On transition into the content review state, the user avatar will be appended to the workflow popup.

All reviewers must agree for a transition to occur.

{state:Draft|approved=Approved|rejected=Rejected}
	{approval:Review|user=&milo,simone|group=&review_leaders}
{state}

If the workflow reviewers are changed whilst in a state with assigned reviewers, the changes will only take effect for the content review on the next transition into that content review state.

Multi-group reviews

In cases where more than one team of reviewers is required, rather than adding the teams to a single approval, just add more {approval} macros to the state and use a different approval for each team.

You can also use conditions to set the order in which the approvals in a state are undertaken.

Credentials

Reviewers can optionally be required to verify their credentials before making a review.

Each approval can be edited to require credentials for the reviewers. Global administrators can set the method of authentication.

See: Reviewer Authentication, Credentials prompt, E-Signatures, E-Signatures Configuration - Global

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 6432948721, 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.

Clear History will remove any added approval roles. Note this will also remove all workflow history.

Macros

Page:

approval macro — Add content-focus reviews to states
Page:

approve-children macro — Approve approvals on child pages
Page:

approve-page macro — Approve an approval
Page:

reject-children macro — Reject approvals on child pages
Page:

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:

pageapprovalassigned
newsapprovalassigned
approvalunassigned

Approval events:

pageapproved
newsapproved
pagerejected
newsrejected

App configuration

Setting	Where	Notes
Workflow Activity and Drafts Visibility	Configuration - Global Configuration - Space Tools	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	Configuration - Global Configuration - Space Tools	During an active review, if the content is updated should existing approvals be reset?
Approval Comment	Configuration - Global	Should comments be mandatory when participating in a content review?
Approval – Assignee	Notifications - Global Notifications - Space Tools	Should assigned reviewers receive email notifications about the content review?
`.approval.minquery`	Advanced Configuration - Global	Set how many characters must be typed when searching for reviewers

Examples

Page:

Adding Multiple Reviews — Add multiple reviews to a content review, set assignee requirements and review dependencies
Page:

Advanced different-space publishing
Page:

Advanced remote-space publishing
Page:

Assignment Examples — Define who can take part in, or be assigned to, a content review.
Page:

Fast-tracked Rejections and Approvals — How to require everyone to Approve, but only need one person to Reject
Page:

Make tasks disable a review — Two ways to use tasks to disable a review. The first way uses a precursor task state where the tasks can be set and completed. The second example uses a Value Reference as a condition to check that all tasks are complete. For the value reference method, you will need the Reporting for Confluence app in addition to Comala Document Management.
Page:

State expiry dates — Using state expiry dates, defining them with metadata, and making them editable
Page:

Using workflow parameters to create reviewer teams in a space — Using workflow parameters to create teams of users for use in approvals

This site has moved to the integrated Appfire documentation and information site for our apps.