In this page

Content status schemes

Content status schemes are the most important part of your content lifecycle management strategy. They define how and when content statuses are assigned to the pages and blog posts in your spaces.

For general information on configuring schemes, refer to the general scheme configuration page.

Content statuses and content status schemes

Content status schemes are named, ordered sets of content statuses. Each status is paired up with a custom CQL (Confluence Query Language) expression to specify which contents should the status be applied to. You may create a scheme specifically for a space, or you can reuse a scheme for multiple spaces.

A content status scheme consists of:

  • a name
  • a description
  • content statuses, each — except the last, default one — having:
    • a CQL query
    • an optional recursive CQL query

You need to choose the CQL queries carefully, and the ordering of statuses is also very important. More on these below.

View the content status schemes

To configure content status schemes, navigate to Confluence Settings (cog icon "⚙" in the top right) → Apps → Better Content Archiving → Configuration → Content status configuration.

The content status scheme list is just like any other scheme list. If you are not familiar with them, learn more about scheme lists, schemes, and how to apply them to spaces.

The Content status schemes tab is selected by default. The list of currently defined content status schemes is shown.

Alternative ways to access the scheme list

This list can also be accessed by clicking the Used in schemes link in the Content statuses list. In this case, the list is filtered on the content status selected.

For Confluence administrators, the content status scheme list is also visible from any space under Space Settings → Integrations → Better Content Archiving. On the Content status scheme tab, click Choose a new scheme and then in the modal, click Manage schemes. Changes made there have the exact same effect as if they were made under Confluence Settings (cog icon "⚙" in the top right) → Apps → Better Content Archiving → Configuration → Content status configuration.

Factory default schemes

The Better Content Archiving app comes with a set of factory default content status schemes. One of them is the "General Content Status Scheme" which is set as default to your spaces.

Reset schemes to default

You can create new schemes, modify them, delete them, and you can also reset schemes to their factory default state. When doing so, you lose all content statuses and content status schemes that you created or customized. There is no undo, so be careful.

Resetting content statuses will change their IDs. This may break existing CQL queries if you rely on IDs instead of status names.

Configure a content status scheme

To create a new content status scheme, click the Add new scheme button on the right above the content status scheme list. To edit an existing one, click the name of a scheme.

The editor modal dialog is opened.

Set the name of the scheme, and add an optional description, then specify the content status assignment rules. In the following sections, each step is described in detail.

Note: if you edit a content status scheme, you may need to run the Refresh content statuses job on the spaces to which that content status scheme is assigned. You are reminded of this by the Content statuses invalid flag.

This flag is also shown if you change the content status scheme of a space under Space Settings → Integrations → Better Content Archiving → Content status scheme. Refer to Jobs for more information on running the Refresh content statuses job.

Step 1: Select content statuses

You have to select at least 1, but no more than 10 content statuses to be added to the scheme. Click the Select content statuses button to do this.

Select the content statuses you want to add to the scheme and click OK.

If you remove a content status, you will be asked for confirmation, because you will lose the custom CQL query specified to the status.

Step 2: Define ordering for content statuses

The order of content statuses is very important. For each page and blog post, the app will try the CQL queries one by one, from top to bottom to see if any of them matches that particular content. A content's status will be determined by the CQL query that first matches the content (direct status) or any of its ancestors (inherited status). If either a direct or an inherited CQL query matches the content, the process stops.

The content status at the bottom is the default content status of the scheme, so it does not allow you to specify CQL queries. This status is essentially a "fallback". It is applied to all contents that do not match any of the CQL queries defined in the scheme.

Drag and drop the content statuses in the list to reorder them.

Step 3: Specify CQL queries

As you already know, CQL queries of a content status scheme are evaluated from top to bottom, one by one until a match is found. It is important that a CQL query defines a more generic condition than the one before as the evaluation process goes down the status list. Otherwise, a generic CQL query that comes first would always override a specific CQL query that comes later.

For each content status added to the scheme, you can see two fields:

  • the CQL field, which is required for all content statuses except for the last one
  • the recursive CQL field, which is optional

A recursive CQL is tested against each descendant but not the page itself.

A few words on CQL queries

When constructing your CQL query, you can use CQL fields that are provided by the Better Content Archiving app.

To the right of the CQL query input box, the CQL fields have an Examples button and a Results button.

The Examples button opens the CQL examples popup which contains a few suggested CQL query samples. Click a sample query to copy to the CQL field.

The Results button displays the number of contents returned by the CQL query. Click it to open the Results popup. In this popup, you can see the first 10 results. This can be useful to quickly verify that your CQL query returns the contents you intend to see.

Note: there are some limitations to the CQL queries that you can use in content status schemes.

  • Although it is technically possible, avoid filtering the result set to specific spaces. Space filtering is handled automatically through space-to-scheme assignments. Adding a clause such as AND space = ... to your CQL queries will interfere with this behavior and will lead to confusing and unexpected results!
  • You should never reference the arch.status* and arch.previousStatus* fields in your content status scheme's CQL queries. Doing so would make status transitions unpredictable, as they would become dependent on the time when the content status is recalculated, which can happen at any moment!
  • You may not search for users (using type="user" or a similar condition). Content status schemes are applied to pages and blog posts only.
  • You may not use ordering (ORDER BY title, for example). Results will be ordered by title implicitly.
  • Avoid using the currentUser() CQL function as its actual value will depend on where you run it from: on the user interface, it will evaluate to you, while inside background jobs it will evaluate to the app user (see the difference here).
Keeping compatibility with quick actions

While content status schemes are highly flexible, some app features (quick actions, Content Status Indicator, content lists, and more) rely on a set of dedicated, predefined properties. When you perform a quick action, such as setting an expiration date for a page, the value is always stored using the corresponding fixed property name. Confluence then makes these fixed property values available in CQL queries through predefined fields.

If this feels too abstract, let's look at a specific example. Assume you set an expiration date for a page using the quick action available in the Content Status Indicator interface. Behind the scenes, this updates multiple records, which are then made available through the following CQL fields:

  • arch.expirationDate
  • arch.expirationDate.inherited
  • arch.expirationDate.setBy
  • arch.expirationDate.setOn

The General Content Status Scheme, which is assigned as the default scheme for all spaces after installation, includes a status called "Expiration date passed". This status uses the following CQL condition: arch.expirationDate < now(). This is how a quick action's update flows through the system and ultimately contributes to a content status.

When designing a custom content status scheme, keep in mind that you are not required to implement statuses based on these built-in fields. Some schemes included with the app also intentionally omit one or more of these fields. However, if you want to integrate with the app’s UI features, we recommend considering which of these fields you want your scheme to support.

Each quick action subpage describes the CQL field requirements you need to maintain to ensure the feature continues to work correctly. The complete list of custom CQL fields is documented here. We recommend reviewing at least the following fields:

  • arch.archivingDate*
  • arch.expirationDate*
  • arch.exclusion*
  • arch.event.lastUpdatedOn
  • arch.event.lastUpdatedBy

Delete a content status scheme

If the content status scheme is not used in any space, and it is also not the default one, you can permanently delete it with the Delete button next to the content status scheme.

Scheme usage is shown in the Used in spaces column. Refer to applying schemes for more details on this.

View the content status scheme of a space

With Confluence administrator or Space administrator privileges, you can view the details of the content status scheme assigned to a space under Space Settings.

Open the space, click Space Settings → Integrations → Better Content Archiving. Select the Content status scheme tab. You can see the read-only view of the content status scheme that is assigned to this space.

Refer to the general configuration for more information on scheme management under Space Settings.

Questions?

Ask us any time.