Approval workflows

Approval workflows are about formally accepting changes made to a document and ensuring that the content meets certain quality criteria.

Breeze brings Confluence page approvals to a whole new level. The workflows are simple and straightforward, yet can be configured to be very strict to fit more regulative environments, e.g. ISO 27001.

This page contains everything needed to understand page approval workflows with Breeze. Please take your time and read carefully.

Setting up an approval workflow

Open Breeze and click Workflows. Then click Create workflow to open the workflow form.

To set up an approval workflow, decide on the options provided in the Approvals section. Then click Save workflow and assign the workflow to one or multiple spaces.

Use draft status for new pages

If this option is selected, newly created pages (in spaces to which the workflow is assigned) get the DRAFT status. Otherwise, newly created pages get the UP TO DATE status by default.

In both cases, the status will change to IN APPROVAL when a user starts an approval request. If the approval is accepted, the page status is set to UP TO DATE. If it is rejected, the page status is set to DRAFT.

Since Confluence permits all third-party apps and users other than the creator to access an unpublished page, the standard approval workflow illustrated above requires that changes made to a page have to be published before requesting approval. While other approval apps stop at this point, Breeze provides an exclusive solution for this problem, which is explained in the following section.

Allow users to create working copies

Working copies are a powerful concept for implementing a more restrictive approval workflow (e.g. for ISO 27001). The main idea is to separate concerns between (1) the editing of pages and requesting approval for the changes, and (2) publishing these changes only after the approval is granted.

This separation of concerns is achieved by allowing users to create working copies, i.e., cloning pages into a predefined working copy space:

The resulting approval workflow is illustrated below. While the original page stays untouched, a working copy gets the DRAFT status and can be edited at will before requesting approval for the changes. After the approval is granted, the approver can automatically merge the changes made in the working copy into the original page. After this, the working copy will be automatically archived (or deleted if you are on the ‘Free’ Confluence plan).

The permissions of users taking part in this workflow can be freely configured via the Confluence space settings:

• Creating a working copy, editing its content, and requesting approval requires a user to have permission to view pages in the original space, and to add/edit pages and comments in the working copy space:

• Approving a working copy and merging its content in the original page requires a user to have permission to edit pages and attachments in the original space, and to edit/delete/archive pages and add comments in the working copy space:

Preset approval options

This option allows to preset the approval type and to prepopulate the list of approvers.

As a result, users requesting approval for a page cannot decide on the type and the approvers but have to use the predefined options of the preset.

If more than one group of approvers is added to the preset, users can decide on one of these approver groups when requesting approval for a page. If the preset contains only one group of approvers, the requesting user cannot select but has to use the one prepopulated list of approvers.

Workflow assignment

Before an approval workflow can be used, it must be assigned to one or multiple spaces.

The assignment of workflows to a space is only permitted to space admins.

Navigate to the Overview component and choose a space. Then click Assign workflow and select a previously created workflow. Confirm by clicking Assign workflow.

Starting an approval request

Page approvals require setting up an approval workflow beforehand.

Creating a working copy

If the workflow is configured to use working copies, users have to create a working copy before requesting approval. To create a working copy of a page, click the content status at the top of the page.

If you have editing permissions for the page, click the … button to access more actions.

Then click Create working copy.

If you have read-only permissions for the page, you do not need to open the more actions menu (because you can’t). Instead, you can directly click Create working copy.

Afterward, click Create working copy. This will clone the content and create a new page with the DRAFT status in the predefined working copy space.

Confluence requires that the pages within a space have a unique name. To avoid conflicting page names, Breeze automatically adds the space key of the original page to the name of the working copy.

Requesting approval

Requesting approval is equal for the standard approval workflow and a workflow using working copies. Therefore, ‘page’ refers to both standard Confluence pages and working copies in the following.

To request approval for a page, click the content status at the top of the page.

If the page has the DRAFT status, click Request approval. If the page has a different status, click the … button and then Request approval in the actions menu.

This will open the following dialog, in which you must specify the approval type, select approvers, and choose an optional due date for the page approval.

There may be less options to choose from if the workflow uses approval presets.

For the approval type, you can choose from the following options:

• Everyone must approve - a page is only approved by a unanimous decision
• First response decides - the first vote of whichever approver decides
• Majority must approve - a page is approved or rejected by a majority vote

Clicking Request approval will set the status to IN APPROVAL and add a page comment, which is used to notify approvers via @mentions and show their decisions when approving or rejecting the page.

When a user is mentioned to approve the page, he receives an email and a message in the Confluence notification center (the bell icon in the main menu bar of Confluence). Confluence also provides Slack notifications, which are explained here.

When selecting yourself as an approver, please consider that Confluence only sends notifications to users different from the one making the @mention.

Using @mentions and, therefore, triggering the built-in notification system of Confluence provides exceptional data privacy by design because notifications are sent via Confluence itself and not via external servers. As a result, Breeze does not process any personal or PII-related data and can send notifications, even without knowing any user names or email addresses.

Approving or rejecting requests

After being notified about the request and checking the content of a page, click the content status at the top of the page.

In the status dialog, you can either click Approve or Reject. If the page is a working copy, the content status dialog also provides a link to the original page and a button for comparing changes made in the working copy with the originally cloned content, allowing approvers to quickly understand what has changed.

After approving/rejecting the page, you can provide a comment. Depending on your choice this is either optional (in case of approval) or obligatory (in case of rejection).

After clicking Approve page (in case of approving) or Reject page (in case of rejecting), your decision shows in the page comments as a reply to the original request.

Depending on the approval type, the page may stay in the IN APPROVAL status (e.g., if not all approvers have made their decision yet) or automatically switch to the UP TO DATE status if it is approved or to the DRAFT status if the approval is rejected.

While the approval request is now finished for standard pages, working copies require one more step, which is merging the approved content of the working copy into the original page.

For this, the latest approver necessary for approving the page is asked to merge the working copy into the original page.

Clicking Merge working copy will merge the content of the working copy into the original page (including attachments) and create a new page version. The user executing the merge will become the author of this new page version.

After the merge, Breeze automatically archives the working copy (for paid Confluence plans) or deletes it (for the free Confluence plan).

The working copy can also be merged at a later time via the more actions menu, which is opened by clicking the ... button in the content status dialog.