Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents
maxLevel2
minLevel2
absoluteUrltrue
excludeOverview
typeflat
separatorpipe

Overview

Excerpt
hiddentrue
Add content-focussed reviews to states

Use the {approval} macro to add content-focussed reviews to workflow states.

Content has to be approved before it can progress to the next state, or it can be rejected to send it back for more edits. Once all reviewers agree – either on Approve or Reject – the workflow will transition to the state defined by the approved or rejected parameter on the parent {state} macro.

Where to use it?

Optional.

One or more {approval} macros can be put in a {state} macro.

Within a {state}, each {approval} must be uniquely named. Can not be used if the {state} has a {state-selection} macro.

Parameters

ParameterRequiredDefaultNotesVer

unnamed first parameter

(tick)(tick)


Name of the content review.

  • Within any {state} macro, each {approval} macro must be given a unique name
  • The name can use any character set supported by your Confluence server – except some reserved characters.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-weight" and label = "example" and space = currentSpace()


description

The description for the approvals:

  • Plain text
  • Can use any character set supported by your Confluence server – except some reserved characters
5.7+
Conditions

Optionally define additional requirements which must be met prior to content approval – see: Conditions.

If one or more conditions are not met, the Approve/Reject buttons will be disabled. However, reviewer assignment will still be possible.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "concept-conditions" and label = "example" and label = "macro-approval" and space = currentSpace()


Reviewers / Assignees

Specify if, who and how reviewers are assigned to the content review.

Parameters selectedapprover, selectedapprovers and (group and/or user) are mutually exclusive. You can use the parameters group and user together.

Prefixing the list with & (ampersand) will auto-assign all users and require them to review (this feature is incompatible with the assignable parameter).


If there are 15 or fewer possible assignees (as specified by the user, group, selectedapprover or selectedapprovers parameters, then they will all be listed by default on the Assigning reviewers screen without the need to perform a search.

assignable
false

Can the user assign reviewers?

  • true – Yes, they can assign reviewers
  • false – No

Note: Assignees must have permission to edit the content and also be member of confluence-users group as a minimum. Other parameters relating to reviewers may enforce further restrictions.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-assignable" and label = "example" and space = currentSpace()

3.2+
credentials
0

To what extent do reviewers need to confirm their identity when reviewing?

  • 0must be logged in (member of confluence-users group)
  • 1 – additionally, must confirm Password
  • 2 – additionally, must confirm Username

The requirements stack, so a value of 2 would mean: Logged in + Password + Username.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-credentials" and label = "example" and space = currentSpace()


exclude

List users who are not allowed to review.

  • A comma-separated list of usernames.
  • Supports Value References (for example: @author@ to prevent content author from reviewing)

Note: While excluded users are not able to be assigned or Approve/Reject, they can still assign other users as reviewers where applicable (eg. if the assignable=true is used).

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-exclude" and label = "example" and space = currentSpace()

4.16+
group

Reviewers must be a member of the specified user group(s):

Note: Users who do not have Edit content permission will not be allowed to review.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-group" and label = "example" and space = currentSpace()


minimum
0 (info)

Define the minimum number of reviewers required for the content review to be approved.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-minimum" and label = "example" and space = currentSpace()


(info) If using the selectedapprover or selectedapprovers parameters, the minimum defaults to 1.

rememberassignees


false

Remember the assignees for reviews with this name?

  • true – any subsequent reviews in the workflow that have the same name as this review (as defined by unnamed first parameter) will automatically have the same reviewers assigned ("sticky assignees")
  • false – don't remember assignees

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-rememberassignees" and label = "example" and space = currentSpace()

4.14+
roles
false

Enable approval roles feature

  • roles=trueapproval roles are enabled, users assigning a review will be able to create and record the role that the reviewer is performing
  • roles=false – approval roles are disabled
6.4+
selectedapprover

A single reviewer must be assigned from the list:

  • A comma-separated list of usernames and/or group names
  • Group names are treated as "a list of usernames"
  • Supports Value References

Note: Users who do not have Edit content permission will not be allowed to review.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-selectedapprover" and label = "example" and space = currentSpace()


selectedapprovers



One or more reviewers must be assigned from the list:

  • A comma-separated list of usernames and/or group names
  • Group names are treated as "a list of usernames"
  • Supports Value References

Note: Users who do not have Edit content permission will not be allowed to review.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-selectedapprovers" and label = "example" and space = currentSpace()


user



Reviewers must be in the specified list:

Note: Users who do not have Edit content permission will not be allowed to review.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-user" and label = "example" and space = currentSpace()


allowedassignusers

Assigners must be in the specified list:

Note: Users who do not have Edit content permission will not be allowed to assign. It can be used along with the allowedassigngroups parameter

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-allowedassignusers" and label = "example" and space = currentSpace()


allowedassigngroups

Assigners must be a member of the specified user group(s):

Note: Users who do not have Edit content permission will not be allowed to assign. It can be used along with the allowedassignusers parameter

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-allowedassigngroups" and label = "example" and space = currentSpace()


User Interface

These parameters are used to customise the user interface of the Workflow Popup.

approvelabel
Approve

Set the caption of the Approve button.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-approvelabel" and label = "example" and space = currentSpace()

5.1+
rejectlabel
Reject

Set the caption of the Reject button.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-rejectlabel" and label = "example" and space = currentSpace()

5.1+

weight


40

When using multiple {approval} macros inside a single {state}, you can use this parameter to set the initial display order.

  • Number ≥ 1
  • Valid values in range of 1 → 232
  • For best results, use multiples of 40.
  • Items of the same weight will be ordered alphabetically A→Z
  • Completed reviews will bubble to the top of the list, in order of completion

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-approval" and label = "parameter-weight" and label = "example" and space = currentSpace()


Deprecated Parameters

The following parameters should no longer be used.

final

Status
subtletrue
colourRed
titleObsolete
Use the final parameter on the published {state} macro instead – see Publishing.


label

Status
subtletrue
titleDeprecated
Use the haslabel condition instead – see: Conditions.

Require that the page or blog has the specified label before a review can be made.


App configuration

SettingWhereNotes
Approval – AssigneeWhile enabled, assignees will receive email notifications about events during the content review.
Approval CommentWhile enabled, reviewers will be forced to comment when they Approve or Reject during content reviews.
Page Update Reset ApprovalWhile enabled, if the content is edited whilst it is under active review then any approvals made during that active review will be reset.
Workflow Activity and Drafts VisibilityWho can see and interact with the Workflow Popup


Example

Code Block
languagetext
themeRDark
{workflow:name=Example}
  {state:Editing|submit=Review|colour=#ffab00}
  {state}
  
{state:Review|approved=Published|rejected=Editing}
   
		{approval:Review this 
Content
page|assignable=true|roles=true}
  {state}
  
{state:Published|final=true|updated=Editing}
  
{state}
{workflow}



Image Modified



If roles=true, a user can be assigned a reviewer role. This can be created when adding the assignee or chosen from any previous role created.

Image Added



Events

Content reviews generate the following Events:

  • approvalunassigned
  • newsapproved
  • newsapprovalassigned
  • newsrejected
  • pageapproved
  • pageapprovalassigned
  • pagerejected

Related macros

The following Macros macros are related to Reviews:

All examples

Content by Label
showLabelsfalse
max500
showSpacefalse
sorttitle
excerptTypesimple
cqllabel = "macro-approval" and label = "example" and space = currentSpace()

See also

Workflow Authoring Guide:

User Guide:

Reporting Guide: