Review workflows

Review workflows are about revising documents in certain intervals to ensure that a knowledge base stays up to date and does not fill with outdated content.

Breeze is the perfect solution for Confluence page reviews. The review workflows define simple conditions for identifying outdated pages in one or multiple spaces and setting their status to REVIEW REQUIRED, which means that a page needs a review, or to ARCHIVABLE, which means a page is no longer needed.

Page reviews and the cleanup of obsolete pages are straightforward and simple to use, yet the workflows are sophisticated enough to fit more regulative environments, e.g., ISO 27001.

Note

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

Setting up a review workflow

Open Breeze and create a new workflow.

To set up a review workflow, enable the Review and Archiving sections. This activates the page statuses REVIEW REQUIRED and ARCHIVABLE and adds review and archiving features to the workflow, which are explained below.

Review

The field Review based on determines the basis upon which pages will be considered outdated and hence receive the status REVIEW REQUIRED. Selecting Page activity means that pages will get marked for review, if they have not been updated or have not been viewed for the number of days specified via the Days without update and Days without view fields.

Note

The Days without update parameter is usually more important because update events can be traced back in time, whereas view events can only be tracked from the day of installing Breeze.

Tip: For big spaces that have not been regularly reviewed, we recommend limiting the number of pages to review by starting with a high number for the Days without update condition. Starting with a higher value, e.g., 365 days, will first identify the pages that haven’t been updated for a very long time. Then, after reviewing those pages, you can progressively lower the number and begin with reviewing pages more frequently.

Note

If existent, the space home page is not part of a review workflow because Confluence does not show a page byline to integrate with third-party apps. As a result, Breeze will always treat a space home page as being up to date.

Selecting Fixed interval means that pages will get marked for review if their last review is longer ago than the number of days specified in the field Days without review.

In that case, the field Earliest review date can be used to delay the first review of pages that have never been reviewed with Breeze before. If it is left empty, those pages will first be marked for review when they are older than the days of the Days without review field.

After deciding on the conditions, you must decide on the responsible reviewers, i.e., which users should be notified when pages are marked for review.

The Notifications field provides a predefined set of user roles to choose from.

• Space owner will notify the owner of the space. Since the space owner is the same for all pages of a space, this means that the corresponding user will be notified for all pages to review in a workflow space. Learn how to assign space owners.
• Page owners will notify the single owner of a page (as specified by Confluence) plus the additional page owners specified with Breeze. This option is recommended for most use cases. Learn how to assign page owners.
• Page creator will notify the user who once created the page. We recommend using the option Page owner instead since the creator cannot be changed in Confluence and depending on the age of a page, chances are high that the user who once created the page has left your Confluence site and is no longer existent.
• Last contributor will notify the user who last updated the page.
• All contributors will notify all users who once updated the page.

In addition to role-based notifications, the Individual notifications field allows the selection of specific users who will be notified for all pages to review within the workflow space.

Archiving

This section contains conditions for labeling pages as ARCHIVABLE, which can be useful for identifying outdated pages that should be removed without further review.

Pages get marked as ARCHIVABLE, if they have not been updated or have not been viewed for the number of days specified via the Days without update and Days without view fields.

The notifications settings are analogous to those in the Review section, i.e., the Notifications field provides a predefined set of user roles to choose from, whereas the Individual notifications field allows to determine specific users to be notified for all archivable pages.

If you enable auto-archiving, the field Days in archivable status determines the number of days after which Breeze will automatically perform the selected Action, which can be either archive or delete. When enabled, the Archiving component will show the remaining days until an archivable page is archived or deleted.

Note

Auto-archiving requires Breeze to have archiving permissions for all spaces to which the workflow is assigned. Learn more about how pages are archived or deleted.

After specifying the workflow conditions, click Save workflow and proceed with the workflow assignment.

Tip: It might be a good idea to name your workflows according to their conditions. As an example, a workflow could be named “Review: 90d no update, Archive: 365 no update”, which corresponds to its conditions that pages will be marked for review if they have not been updated for 90 days or will be marked for archiving if they have not been viewed for 365 days. A proper naming convention will help to distinguish workflows just by their names.

Workflow assignment

To assign a workflow to one or multiple spaces, click Update assigned spaces….

Search for the desired spaces and add them to the assignment list.

Note

The search requires full words, i.e. type ‘Project ’ (with a space at the end) to find all spaces beginning with the word ‘Project’.

Click Update assignments to assign the workflow to the selected spaces.

Note

Workflow assignment requires admin permissions for each selected space.

Workflow customization

By default, the review workflow settings will be applied to all pages of its assigned spaces. While different workflows can be used for different spaces, workflow customization satisfies the demand for a more flexible way of managing review conditions for various parts of one space.

To customize the review workflow for a page and all its descendants, open the Overview component and click on the ”…” button at the very right.

Select Review & Archiving to open the customization form.

Currently, Breeze supports the customization of pages to review and pages to archive. Custom settings do not override notifications, i.e., the page and its descendants use the same settings as the associated space workflow.

Click Save to apply your customized review and archiving conditions to the selected page and all its descendants.

Note

Customization overrides the review and/or archiving conditions of the space workflow. Custom settings will have no effect if the space workflow has been set up without review/archiving conditions.

If custom review and/or archiving conditions are defined, the Overview component will show a yellow and/or red dot indicating that this page defines a customization for itself and all its descendants. Details show up when hovering over these indicators.

Note

A descendant inheriting a customization from a parent page can customize review and/or archiving conditions itself by following the same logic explained above.

Executing review workflows

Executing a review workflow means that Breeze looks through all pages of an assigned space and labels outdated pages as REVIEW REQUIRED or ARCHIVABLE, depending on the workflow’s conditions. It also means that Breeze creates a report, which mentions responsible users to take action on the results.

Note

The execution of a workflow, the creation of a report, and sending notifications are all coupled with each other.

Manual execution

Manually executing a workflow is useful when a space has not been analyzed yet and to get an immediate report containing the identified pages to review.

Note

Only space admins can trigger the manual workflow execution.

A workflow can be manually executed in the Overview component by clicking Analyze space and then Analyze space now.

Automated execution

While manual workflow execution is useful for getting immediate results for an individual space, Breeze also provides an automatic workflow execution to ensure that all spaces with an assigned workflow are regularly checked for outdated pages.

By default, the automatic workflow execution is enabled and configured so that workflows are executed every four weeks on Sunday. To disable the automatic execution of workflows, or change the execution interval or the day of execution, go to the global app settings.

If the automated execution of workflows is enabled, the remaining days until the next execution are displayed in the app’s main menu bar.

Reviewing pages

After a workflow execution, the pages to review are contained in the space’s latest report.

In addition, pages with the status REVIEW REQUIRED are listed in the Review component, and pages with the status ARCHIVABLE are listed in the Archiving component.

When opening a page to review, the current status is shown at the very top.

After checking (and perhaps updating) the content, a reviewer should click the status to open the page status dialog.

If the page is still relevant, the reviewer clicks the Up to date button, which will reset the page to the UP TO DATE status.

Note

Resetting a page will also reset the workflow conditions, which have caused the page to be marked for review. As an example, a page might be marked for review by a workflow because it was not updated for 90 days, as specified in the corresponding workflow conditions. If the page is reset it will be marked by the workflow again in 90 days at the earliest.

If the page is considered obsolete, the reviewer clicks the Archivable button, which will set the status to ARCHIVABLE. In this case, the reviewer can add a comment, which will show in the archiving component and help space admins (or persons responsible for archiving) understand why this page is no longer needed.

Reviewing all pages of a page tree in bulk

To review all pages of a page tree and set their status as either UP TO DATE or ARCHIVABLE, open the page status dialog of the parent page. Then open the more actions menu by clicking the … button.

In case of marking all pages as UP TO DATE, select Mark page as up to date. In the corresponding dialog, select the option Mark descendants as up to date before clicking the Mark as up to date button.

To bulk review not an entire page tree but an arbitrary selection of pages, use the Review component.

Manually marking pages for review or archiving

While Breeze identifies pages to review during a workflow execution, pages can also be manually marked as REVIEW REQUIRED or ARCHIVABLE by a user. These statuses can be set for single pages or complete page trees, which is, for example, useful when a page tree contains all information of a particular project that has been finished and hence shall be marked for archiving.

Note

The status of pages manually marked for review or archiving stays to ensure it is not overridden by a succeeding workflow execution.

To set the status, open the page status dialog on top of the page and click the … buttton.

Then select Mark page for review or Mark page as archivable.

In the following dialog, you can decide to also mark descendants of the page, i.e., all sub-pages below the current page in the page tree. In the case of marking pages as ARCHIVABLE, you can also provide a comment, which will afterward show in the archiving component of Breeze.

Note

Marking a complete page tree may take a while and depends on the number of pages within the tree. Please make sure not to click and keep the popup open until the operation is completed.

Excluding pages from the review workflow

Depending on your Confluence content, you may want to exclude pages from the workflow execution, i.e., set the EXCLUDED status, which prevents Breeze from marking these pages for review or archiving.

A typical use case might be pages with content known to not change over time, like the company vision, corporate ID, or branding material.

Note

Another example are the Breeze reports. Once created, a report does not change, which is why these reports are excluded by default.

To set the EXCLUDED status, click the current status to open the page status dialog and then click the … button.

Then click Exclude page.

Afterward, you can decide to either exclude the single page and/or to exclude all descendants, i.e. all pages below the current page in the page tree.