Page Approval Plugin

The page approval macro provides a simple and flexible way of managing and processing approval of Confluence pages. The macro keeps to the wiki philosophy of decentralisation and user empowerment. The default usage of the macro does not require any administration and hence can be managed by the wiki community. The macro also contains parameters that allow specification of approval groups, notifications, approval order and more.

For support pricing details please check the "Detailed Information" tab.

Details

Structured Approval Features

Note that is is possible to user the macro to define a more structured approval process. This is done by using the 'users' and 'chain' parameters as follows:

Users can be manually added to the list of required approvers of a page by adding their user name in the 'users' parameter of the macro.
The 'chain=yes' parameter can be added to make the approval follow the order of the users that are specified by the 'users' parameter.
Approvers can be specified to be the members of a group by using the 'approvalGroup=' parameter.

Dynamic Data

Dynamic data can invalidate the approval of a page because the page can change without an edit. For instance, the include macro could show different text based upon what is in the included page, independant of anything in the approval page. To get around this problem, most macros are considered 'unapprovable'. There are a number of standard macros (including 'panel', 'toc', etc.) that can be approved, and these have been hard coded into the macro.

Overview

General Features

Screenshots

Report seen when not all registered approvers have approved a page.	View seen on a page when not all registered approvers have approved that page.	View seen from an unregistered approver - "Register" button allows them to register themselves

View seen when acknowledgments are activated but hidden, and the page has been approved. Note the "Show Acknowledgers" link and that this has been set at the space level.	View seen when acknowledgments are activated and the page has neither been approved nor acknowledged. Note the "Hide Acknowledgers" link and that this is set at the space level.

Approvals

Users can approve or unapprove pages, which sets a flag at the top of the page to appropriately indicate whether the page has been approved or not, and by whom.

Anybody can register as an 'approver' of any page. This is done by clicking on the 'register' hyperlink. An important concept behind the macro is that users can define the approval process by simply adding themselves as an approver.
Pages are approved when all the registered approvers mark the page as approved.
A page is marked as 'unapproved' until all the people in the approval list have approved it.
Pages with registered approvers display the list of people who have registered as approvers.
Users who view a page that is not approved are able to easily navigate to the last approved version by clicking on the relevant link.
Approvers can unregister themselves without affecting the approval status of documents they approved in the past. However, this may affect the approval state of pages that are currently unapproved (i.e. if the user removes themselves from a page where they were only person left to approve the page, then the page would be approved.
The use of dynamic macros makes page approval impossible, because content of the dynamic data can change at any time. The page approval macro will not allow pages with unknown macros to be approved (see the note on dynamic data below for more details).
If a page is changed after it was approved, the approval (and acknowledged) status for all users is reset to blank. The status is also reset if any of the page's attachments are changed.

Acknowledgements

Acknowledgements are a good way to ensure that particular users have indicated they have checked the page, even if they are not approvers. For example, users in a project team can be added as acknowledgers so that the team leader knows a page has been read, however only the team leader has the authority to be the approver of the page.

Users may also mark the page as 'acknowledged' if the 'showAcknowledgement' parameter is specified in the macro's parameters or in the space or global level settings.
Users can register themselves as acknowledgers in the same manner as approvers, by clicking on the "Register" button under the Acknowledgers table.
The Acknowledgers table can be hidden if it is taking up too much room, by clicking on the "Hide Acknowledgers" link. When the acknowledgers are hidden, this link becomes "Show Acknowledgers" to show this table again. This setting is not remembered, but can be set in the parameters - please see the "acknowledgersVisible" parameter in the {pageapproval} page.

Other Features

Notifications can be setup such that users are notified (by email) of changes in the approval state of a page.
Administrators can unregister any user.
The 'copy' parameter can be used to copy approved pages to another space within Confluence.

Global Settings

Some parameters that can be configured as part of the {pageapproval} macro (see link for details on these parameters) can be configured globally in the Confluence Admin Console.

1. Click on the Page Approval Properties link:

2. The following screen will appear to control particular parameters globally:

Space-wide Approvals

As of version 1.14, Page Approval can now be added on a space level, as well as a page level. This will automatically add the Page Approval content into any page in a given space. To configure the space level page approval, you must be an administrator or have space admin privileges. To setup the space level of page approval, choose 'Page Approval' from the 'Browse' menu in the space that you want the macro added to.

Note: if there is a page approval macro directly on any page within the space, the page level will take precedence over the space level.

This will lead you to the space level configuration screen.

Here you can configure the settings for all pages in the space. These will be automatically applied and updated to any pages in the space when changes are made.

Please see the {pageapproval} documentation for details on the individual options. There is also an option for Ignored Pages which will allow you to list any pages which will be ignored when adding space-wide page approvals. For example, if you want every page except for your Home page and your Navigation page to have a space-wide page approval, you would add 'Home, Navigation' into the text box. You may also use the keyword '@all' to tell the plugin not to add a space-wide pageapproval to any page. This can be used if you want to select only a few pages which will have a space-configured page approval on them, but have them all use the space settings and update when the space settings are changed. For example, if you have a space with a few pages that need to have the same page-approval on them, you can turn on space-wide page approval and choose all your settings, using '@all' for ignore pages. Then on the required pages, manually add the macro {pageapproval} onto these pages, and they will all stay consistent with the same settings as retrieved from the space settings page.

An extra option to "Allow All Macros" is provided at a space level so that individual macro names do not need to be specified. Please note that this setting will allow any macros that may change content on the page to be used on any page in the space, and that any changes attributed to these macros will not be tracked by the Page Approval plugin.

Usage and Examples

General Usage

This code makes approval by the users admin, msith and bob brown mandatory.

{pageapproval:users=admin, msmith, bob brown}

This gives the approvals an expiry date.

{pageapproval:expirymonth=12|expiryday=30} - page approval expires every year on December 30th.
{pageapproval:expirymonth=11} - page expires every year on the first day of November

This code also displays the acknowledgement status of the page.

{pageapproval:showAcknowledgement}

Setting up Notifications

The following code sets up notifications to all registered users to be notified of all changes:

{pageapproval:notifiedusers=all|notifyapprovals=true|notifyacknowledgements=true|notifiedactions=change}

The following code sets up notifications to all registered users to be notified if a page has been approved or unapproved, but not on acknowledgement actions:

{pageapproval:notifiedusers=all|notifyapprovals=true|notifyacknowledgements=false|notifiedactions=change}

The following code sets up notifications to only those users who have approved a page if the page is unapproved:

{pageapproval:notifiedusers=approved|notifyapprovals=true|notifiedactions=unapproval}

Bugs & Feature Requests

Bug reports and feature requests are available in JIRA.

Release History

You can view the full release history here.

To view the macro's documentation, click on its name below.

For information on installing the plugins once you've downloaded them, see these instructions.
For plugins compatible with pre-Confluence 4.x see these instructions.