---
title: "approval macro"
canonical: "https://support.appfire.com/space/CDML/649662337/approval%20macro"
format: markdown
---
> Macro (aura-html)


## Overview

> Macro (excerpt)
> 
> Add content-focus reviews to states

Use the `approval` macro to add content-focused 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 on the review decision – either reviewers all have **Approved** or all have **Rejected **– the workflow will transition to the state defined by the `approved` or `rejected` parameter on the parent [state macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531575).

## Where to use it?

Optional.

One or more `approval` macros can be put in a [state macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531575).

Within a state, each `approval` must be uniquely named. 

:blue_star: An `approval` cannot be used in a state if the state has a [state selection macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826719).

## Parameters

| Parameter | Required | Default | Notes | Ver |
| --- | --- | --- | --- | --- |
| *unnamed first parameter* | :check_mark: |  | Name of the content review.<br>- 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859070).<br>> Macro (contentbylabel) |  |
| `description` |  |  | The description for the approvals:<br>- plain text
- can use any character set supported by your Confluence server – except some [reserved characters](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859070). | 5.7+ |
| `label` |  |  | Requires that the content has the specified label for the approval to be active.<br>- only one label can be used
- the label cannot contain , !, #, &, (, ), *, ,, ., :, ;, <, >, ?, @, [, ], ^
- the label cannot be negated<br>If the content does not have the specified label:<br>- the Approve/Reject buttons are disabled.
- reviewers cannot be manually assigned to the approval if the approval includes `assignable=true`
- if the approval is one of several approvals in a state ([multiple reviews](#)) it is not required for the transition<br>If the addition of the specified label is a requirement ([condition](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694110)) for the the approval to be undertaken then use the `haslabel` condition instead. |  |
| *[Conditions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694110)* |  |  | Optionally define additional requirements ([conditions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694110)) which must be met prior to content approval .<br>If one or more conditions are not met, the Approve/Reject buttons will be disabled. However, reviewer assignment will still be possible.<br>> Macro (contentbylabel) |  |
| ## Reviewer/Assignee Parameters<br>Parameters to specify if, who and how reviewers are assigned to the content review.<br><sup>† </sup>Parameters `selectedapprover`, `selectedapprovers` and ( `group` and/or `user` ) are mutually exclusive. You can use the parameters `group` and `user` together.<br><sup>‡</sup> Prefixing the list with `&` (ampersand) will auto-assign all users and require them to review (this feature is incompatible with the `assignable` parameter).<br>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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650347935) screen without the need to perform a search.<br>The default number (15) of possible assignees listed on the [Assigning reviewers](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650347935) screen can be changed in [Advanced Global Configuration](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649529530). |
| `assignable` |  | `false` | Can the user assign reviewers?<br>- `true` – Yes, they can assign reviewers
- `false` – No<br>Note: Assignees must have permission to edit the content and also be member of [confluence-users group](https://confluence.atlassian.com/doc/confluence-groups-139478.html) as a minimum. Other parameters relating to reviewers may enforce further restrictions.<br>> Macro (contentbylabel) | 3.2+ |
| `credentials` |  | `0` | To what extent do reviewers need to confirm their identity when reviewing?<br>- `0` – **must be logged in** (member of [confluence-users group](https://confluence.atlassian.com/doc/confluence-groups-139478.html))
- `1` – additionally, must confirm **Password / Signing Token**
- `2` – additionally, must confirm **Username**<br>The requirements stack, so a value of `2` would mean: ‘Logged in + Password / Signing Token + Username’.<br>The method of authentication can be configured globally. The options above for the credential password can be set to be based on either:<br>- *a user's Confluence credentials*
- *a signing token generated by a third-party app.*<br>> Macro (contentbylabel)<br>> Macro (contentbylabel) |  |
| `exclude` |  |  | List users who are not allowed to review.<br>- a comma-separated list of usernames.
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) (for example: `@author@` to prevent content author from reviewing)<br>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).<br>> Macro (contentbylabel) | 4.16+ |
| `group`<sup>†</sup> |  |  | Reviewers must be a member of the specified user group(s):<br>- a comma-separated list of group names<sup>‡</sup>
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)<br>Note: Users who do not have [Edit content permission](#) will not be allowed to review.<br>> Macro (contentbylabel) |  |
| :yellow_star: When `group` is applied to the **approval** macro** it is not used as a ****[condition](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694110)**** for the approval macro **- it is an approval macro parameter.<br>You can prefix the first list item with the `&` (ampersand) to mandate that all users in the groups defined by the list must take part in the content review. |
| `minimum` |  | :info: | Define the minimum number of reviewers required for the content review to be approved.<br>- default is at least one user must approve
- if you need more users, then specify number  ≥ 2
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) (v4.18+)<br>If more than the minimum number of users are assigned as reviewers then all assignees must undertake and agree the approval.<br>> Macro (contentbylabel) |  |
| :info: If using the `selectedapprover` or `selectedapprovers` parameters, the `minimum` defaults to `1`. |
| `rememberassignees` |  | `false` | Remember the assignees for reviews with this name?<br>- `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<br>> ℹ️ `The rememberassignes` parameter, when `true`, remembers preassigned reviewers who have been unassigned.<br>> Macro (contentbylabel) | 4.14+ |
| `roles` |  | `false` | Enable approval roles feature<br>- `true` – [approval roles](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859574) are enabled, users assigning a review will be able to record the role that the reviewer is performing
- `false` – approval roles are disabled | 6.4+ |
| `selectedapprover`<sup>†</sup> |  |  | A single reviewer must be assigned from the list:<br>- a comma-separated list of usernames and/or group names
- group names are treated as "a list of usernames"
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)<br>Note: Users who do not have [Edit content permission](#) will not be allowed to review.<br>> Macro (contentbylabel) |  |
| `selectedapprovers`<sup>†</sup> |  |  | One or more reviewers must be assigned from the list:<br>- a comma-separated list of usernames and/or group names<sup>‡</sup>
- group names are treated as "a list of usernames"
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)<br>Note: Users who do not have [Edit content permission](#) will not be allowed to review.<br>> Macro (contentbylabel) |  |
| `user`<sup>†</sup> |  |  | Reviewers must be in the specified list:<br>- a comma-separated list of usernames<sup>‡</sup>
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)<br>Note: Users who do not have [Edit content permission](#) will not be allowed to review.<br>> Macro (contentbylabel) |  |
| :yellow_star: When `user` is applied to the approval macro** it is not used as a ****[condition](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694110)**** for the approval macro **- it is an approval macro parameter.<br>You can prefix the list (not items in the list) with `&` (ampersand) to mandate that all users in the groups defined by the list must take part in the content review. |
| `allowedassignusers` |  |  | Assigners must be in the specified list:<br>- a comma-separated list of usernames
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)<br>Note<br>- users who do not have [Edit content permission](#) will not be allowed to assign. It can be used along with the `allowedassigngroups` parameter.
- adding this parameter does not disable the review for users who have [Edit content permission](#) until a reviewer has been assigned. To prevent the review from being undertaken before assignment of a reviewer, use this parameter in conjunction with one of  `selectedapprover` or  `selectedapprovers` parameters.<br>> Macro (contentbylabel) |  |
| `allowedassigngroups` |  |  | Assigners must be a member of the specified user group(s):<br>- a comma-separated list of group names
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)<br>Note<br>- users who do not have [Edit content permission](#) will not be allowed to assign. It can be used along with the `allowedassigngroups` parameter.
- adding this parameter does not disable the review for users who have [Edit content permission](#) until a reviewer has been assigned. To prevent the review from being undertaken before assignment of a reviewer, use this parameter in conjunction with one of  `selectedapprover` or  `selectedapprovers` parameters.<br>> Macro (contentbylabel) |  |
| ## User Interface Parameters<br>These parameters are used to customise the user interface of the [Workflow Popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846). |
| `approvelabel` |  | `Approve` | Set the caption of the Approve button.<br>> Macro (contentbylabel) | 5.1+ |
| `rejectlabel` |  | `Reject` | Set the caption of the Reject button.<br>> Macro (contentbylabel) | 5.1+ |
| `weight` |  | `40` | When using multiple `approval` macros inside a single state, you can use this parameter to set the *initial* display order.<br>- 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<br>> Macro (contentbylabel) |  |
| ## Deprecated Parameters<br>The following parameters should no longer be used. |
| `final` |  |  | [Published] Use the `final` parameter on the published [state macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531575) instead – see [Publishing](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649923873). |  |

## Example

```plaintext
{workflow:name=Example}
    {state:Editing|submit=Review|colour=#ffab00}
    {state}
    {state:Review|approved=Published|rejected=Editing}
        {approval:Review this page|assignable=true|roles=true}
    {state}
    {state:Published|final=true|updated=Editing}
    {state}
{workflow}
```

<span style="color: #ffffff">o</span>> Macro (inline-media-image)



When `roles=true` is added to the approval macro, users assigned to the content review can be assigned a role.

A reviewer role can be created when adding the assignee or chosen from a dropdown menu listing of previously added roles for other assignees.

![image](media://fe52974f-fb3a-4d2d-922b-ed6676c1f980)

Roles for assignees can be enabled for each individual approval by editing the approval in the workflow builder.

![image](media://b8d8f377-70d1-4756-91af-a206af8cb20d)

## Events

Content reviews generate the following [Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655):

- `approvalunassigned`
- `newsapproved`
- `newsapprovalassigned`
- `newsrejected`
- `pageapproved`
- `pageapprovalassigned`
- `pagerejected`

## Related macros

The following [macros](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650151673) are related to [reviews](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650153766):

- [approve-page](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826933)
- [approve-children](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531735)
- [reject-page](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563317)
- [reject-children](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649793152)
- [state](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531575) – `approved` and `rejected` parameters

## All examples

> Macro (contentbylabel)

### See also

[Workflow Authoring Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648611901)

- [Reviews](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650153766)
- [States](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649595551)
- [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425)
- [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) – [Attribute References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649728358), [Event references](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649925434)

[User Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648907144)

- [Content reviews](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650313809)

[Reporting Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649070833)

- [Workflow Report Macro - Approvals](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650120822)

[Configuration - Global](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649889951)

- [Advanced Configuration - Global](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649529530)