Assignment Examples

Overview

These examples show a number of configurations of the {approval} macro parameters which control who can take part in, or assign users to a content review.

View-only users

Users who only have View content permission can take part in a content review so long as they can see the workflow popup (requires Workflow Activity and Drafts Visibility option to be set to Anybody).

No assignment

By default, a content review will not allow reviewer assignment.

Any single user with Edit content permission can Approve or Reject the review.

{workflow:name=No assignment}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review}
   {state}
   {state:Published}
   {state}
{workflow}

Assign anyone

To allow anyone to be assigned, add the assignable=true parameter.

The workflow popup will show the + Add reviewer button:

In this scenario:

• If there are no assignees, any single user can complete the review
• Users in the confluence-users group (all registered Confluence users) can be assigned to the review.
• If anyone is assigned, only the assignee(s) can complete the review
• If multiple people are assigned, they must all agree, either Approve or Reject, to complete the review

{workflow:name=No assignment}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|assignable=true}
   {state}
   {state:Published}
   {state}
{workflow}

Excluding reviewers

You can use the exclude parameter to define one or more users who can not take part in the review. The Approve and Reject buttons will appear disabled for the excluded users. However, if the review is assignable, they will still be able to assign other users to the review.

The excluded parameter takes precedence over the group, selectedapprover, selectedapprovers and user parameters (see below).

A common exclusion use is for the person who created the content. This can be achieved with the @creator@ user reference.

{workflow:name=No assignment}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|assignable=true|exclude=@creator@}
   {state}
   {state:Published}
   {state}
{workflow}

Minimum reviewers

You can specify how many people must be assigned to undertake the approval of the content using the minimum parameter.

The workflow popup will indicate the number of reviewers required by displaying a number of outline avatars. But more reviewers can be added if desired. 

Users can be assigned as reviewers by choosing the + icon in the popup.

The approval has two added parameters:

• assignable=true allows the assignment of reviewers
• minimum=2 sets the required number of approval decisions for the transition to occur
  
  

{workflow:name=No assignment}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|assignable=true|minimum=2}
   {state}
   {state:Published}
   {state}
{workflow}

All assigned reviewers would have to agree on either Approve or Reject in order to complete the review. For the Approve decision, the number of review decisions must also at least meet the minimum requirement if present.

If more than one reviewer is assigned you can fastrack a reject transition by adding a trigger to the workflow. This negates the need for all assigned reviewers to agree on a Reject decision for the rejected transition to take place.

Limiting assignment

You may want to limit which users or groups are allowed to assign a reviewer for the approval i.e., who can be an assigner. You can choose to use the allowedassignusers and/or the allowedassigngroups parameter.

{workflow:name=Allow Assigners}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|assignable=true|allowedassignusers=elle|allowedassigngroups=assigners}
   {state}
   {state:Published}
   {state}
{workflow}

In the example above, only a user who is a member of the Confluence group assigners or user elle can assign reviewers in the Review approval. The assignable=true parameter must also be included to allow the assignment of reviewers for the approval.

Be aware that until the review has been assigned it can be undertaken by anyone with view and edit permissions.

So if you only want the review to be undertaken once a reviewer has been assigned you can use the allowedassignusers and/or allowedassigngroups parameters together with the selectedapprover or selectedapprovers parameters.

{workflow:name=Allow Assigners}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|allowedassignusers=elle|allowedassigngroups=assigners|selectedapprovers=matilde,suni,adam}
   {state}
   {state:Published}
   {state}
{workflow}

The allowed assigners are only the user elle and members of the Confluence user group assigners. These users will see the option to +Add reviewer in the workflow popup.

The Approve and Reject buttons are disabled for the assigners.

Except for the allowed assigners all other users will view the workflow popup with the content review buttons disabled and with no option to assign reviewers.

Reviewers must be assigned to undertake the content review.

Allowed assigners can choose  +Add reviewer to open the reviewer assignee dialogue box. The choice of reviewers is limited to the users specified by the selectedapprovers parameter.

These parameters can also be combined with other parameters, for example, user or group if you want to automatically assign a user beforehand and/or the minimum if you require more than one reviewer to undertake and agree the review.

Note: the assignable parameter must be true when using allowedassignusers/allowassigngroups parameter unless one of the selectedapprover or selectedapprovers parameters are used. 

You can use the ! operator if you want to allow any user to assign reviewers except specific listed ones. In the example below any user except horst and ahmed will be allowed to assign:

{approval:Review|assignable=true|allowedassignusers=!horst,ahmed}

Limiting selection

If you want to limit which users or groups can be assigned to a review, use the user and/or group parameters.

{workflow:name=No assignment}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|assignable=true|minimum=2|group=reviewers|user=suni,moises}
   {state}
   {state:Published}
   {state}
{workflow}

In the example above, anyone from the listed group and individual users can take part in the review, and optionally be assigned beforehand. A minimum of two reviewers is required to complete the review.

If the cumulative number of users specified by these parameters is 15 or fewer then, they will automatically be listed, without the need to search, when assigning reviewers.

Note: If you don't require users to be assigned prior to reviewing, you can remove the assignable parameter. Only the users listed by the group and/or users parameters will be able to Approve or Reject, without the need for assignment.

Automatic assignment

If you want to automatically assign one or more users and/or groups, use the group and/or user parameter(s) but prefix the value with & (ampersand).

Note: The assignable=true and minimum parameters will be ignored when automatic assignment is applied.

{workflow:name=No assignment}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|group=&reviewers,project_leads|user=&moises, suni}
   {state}
   {state:Published}
   {state}
{workflow}

In the example above, all users from the specified Confluence user groups and all the individual Confluence users listed are automatically assigned to the review. 

At least one assignee

The selectedapprovers parameter allows you to specify one or more users and/or groups, and automatically sets minimum=1.

The two examples below have the exact same effect.

{approval:Review|selectedapprovers=user1,group1}

{approval:Review|user=user1|group=group1|minimum=1}

In the example:

{approval:Review|selectedapprovers=milo,matilde,moises}

An editor choosing +Add reviewer in the workflow popup would be able to select one or more of the listed users as a reviewer.

The user must be assigned before they can Approve or Reject.

• additional reviewers can be assigned before the approval transition
• existing assigned reviewers can be unassigned if they have not yet undertaken a decision

Exactly one assignee

If you want to mandate that one person is assigned, and no more, use the selectedapprover parameter.

{workflow:name=No assignment}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|selectedapprover=milo,matilde,moises}
   {state}
   {state:Published}
   {state}
{workflow}

In the example above, only one person from the listed  users (and if present listed groups) can take part in the review.

Users must be assigned before they can Approve or Reject.

• only one reviewer can be assigned
• once a reviewer is assigned the +Add reviewer option is removed from the workflow popup
• an assigned reviewer can be unassigned before they have undertaken the approval decision