Set retention rules to delete unwanted data

This feature is available with a Confluence Data Center license.

When you edit a page or attached file, Confluence stores the previous content so you can restore it if you need to. Over time these historical versions start to add up, increasing the size of your database and attachments directory.  It's not uncommon for some pages to have hundreds of historical versions, or for a space to have hundreds of items in the trash. 

On this page:

Retention rules allow you to automatically delete historical versions of pages and attachments, and purge deleted items from the trash. You can:

  • set global rules that will apply to all spaces
  • define exemptions for spaces that have special requirements, and need different rules
  • allow space administrators to set rules for their spaces.

Global retention rules screen showing global rules and a list of space exemptions with different rules.

Screenshot showing global retention rules administration screen

Retention rule criteria

You can set a retention rule for:

  • historical page versions (pages only, you can't set a retention rule for blog posts)
  • historical attachment versions, and
  • items in the trash.

The criteria you can use to determine what should be deleted is outlined below. 

Rule criteriaPage and Attachment versionsTrash
Keep all (default)Historical versions will not be automatically deleted. Items will not be automatically purged from the trash
Keep by age

Keep versions for a specific amount of time.

For example you could set it to automatically delete any version older than 2 years. 

Keep deleted items in the trash for a specific amount of time.

For example you could set it to purge any item deleted more than 3 months ago.

Keep by number

Keep a maximum number of versions.

For example you could set it to keep the 5 most recent versions, and automatically delete any earlier versions.  

Not applicable for trash. 

It's important to note that for page and attachment versions, the latest version is never deleted, only the history. Retention rules never prevent people from creating new versions.

How versions are deleted

A scheduled job will permanently delete any items that don't the meet retention rules. This "soft" job runs every 10 minutes and deletes items in small batches (of about 3000 items) to ensure there's no performance impact to your site. When you first set a rule, the job may need to run quite a few times before all items that don't meet that rule are deleted. 

If you need to delete versions more quickly, you can manually run the "hard" job, which will delete all items that don't meet the rules in one cycle. This can have a performance impact however, so you might want to only run the hard job when Confluence is less busy. 

See Scheduled jobs to learn more about these jobs and how to run or disable them.

Each version deleted or item purged from the trash is written to the audit log if the End user activity coverage area is set to Advanced or higher. 

Define your retention strategy

Before you set any rules, it's important to define your retention strategy. Historical versions and trash that don't meet the retention rule criteria will be permanently deleted, and can't be restored, so it's essential you get it right. 

Global rules vs space exemptions

There are two approaches you can take:

  • Set your global rule to keep all, and use space exemptions to target individual spaces that can be cleaned up more aggressively. 
  • Add space exemptions for the spaces where you need to retain history and trash, and set these to keep all, then set a global rule to clean up all remaining spaces.

The order that you set your rules is important - once you set a global rule, it will start deleting almost immediately. Make sure all your exemptions are in place first. 

Here's some example scenarios to help you think through your strategy. 
 

Scenario 1...

Mia is the administrator of a large Confluence site that has been active for about 8 years. Backups and upgrades have become increasingly difficult due to the database and attachment directory now weighing in at over 10 terabytes. 

To reduce Confluence's footprint, the Mia:

  • Discusses various options with stakeholders, and decides to put in place an aggressive global retention rule. 
  • Communicates the plan to stakeholders in their organisation, including the date the global rule will be set.
  • Makes a note of the current size of the database and attachments directory
  • Sets the following global retention rules
    • Page versions - keep by age - 2 years
    • Attachment versions - keep by age - 1 year
    • Trash - keep by age - 6 months

Within a few days, Mia observes a reduction in the size of the database, and a huge 1tb reduction in the size of the attachments directory, both of which contribute to a noticeable decrease in backup time. 

Scenario 2...

Omar administers the Confluence site for an insurance company. Omar would like to clean up the site, but knows that some teams need to keep detailed records of their work, for auditing and compliance purposes. 

To clean up unnecessary data Omar:

  • Discusses various retention rule options with the compliance team. They decide that the best approach is to keep everything by default, but empower individual teams to make decisions about their own spaces. 
  • Leaves the global retention rules as
    • Page versions - keep all
    • Attachment versions - keep all
    • Trash - keep all
  • Sets the exemption permissions to allow system administrators and space administrators to manage retention rules.
  • Communicates to team leads that they can set their own rules in Space Tools, and points them to a page prepared by the compliance team which outlines what data must be kept, and for how long. 

Within a few days, Omar sees exemptions appearing in the space exemptions list, as several teams add their own retention rules. 

Scenario 3...

Fran administers several different Confluence instances that have sprung up across the organisation as a result of acquisitions over the years. They're in the process of consolidating all their sites, and plan to move some of them to Confluence cloud over the next year or so. 

Fran wants this process to be as smooth as possible, and doesn't really want to migrate a huge amount of unnecessary historical data.  Fran:

  • Uses Analytics to make a short list of spaces that have not been viewed or edited in the last 6 months.
  • Informs space owners that much of the version history will soon be removed.
  • Leaves the global retention rules as:
    • Page versions - keep all
    • Attachment versions - keep all
    • Trash - keep all
  • Adds an exemption for each space that can be cleaned up, and sets a very agressive retention rule:
    • Page versions - keep by number - 5 versions
    • Attachment versions - keep by number - 2 versions
    • Trash - keep by age - 1 month

When the time comes to start migrating spaces to their new cloud instance, Fran prioritises the cleaned up spaces, and finds the migration happens more quickly as there is significantly less data to transfer. 

Delegate responsibility to space administrators

You'll need to decide whether to allow space administrators to manage retention rules for their spaces. This allows the administrators most familiar with the content to make decisions about how long to keep historical versions and items in the trash. 

See Allow space administrators to manage exemptions.

Change the global retention rules

Check the considerations for administrators before changing retention rules. 

You need system administrator global permissions to do this.  

To change a global retention rule:

  1. Go to Administration  > General Configuration > Retention rules.
  2. Select Edit under Global retention rules.
  3. Under Page versions select Keep all, Keep by number, or Keep by age,  and then enter a value (if required).
  4. Under Attachment versions select Keep all, Keep by number, or Keep by age, and then enter a value (if required).
  5. Under Trash, select Keep all, or Keep by deleted date, and then enter a value (if required).
  6. Choose whether to allow space administrators to set retention rules for their space.
  7. Save your changes.

These rules will apply to all spaces in your site, unless an exemption has been added for a particular space.  This includes personal spaces and archived spaces. 

Global retention rules screen showing the current rules

Screenshot showing global retention rules

Add a space exemption 

For the situations where you don't want a global retention rule to apply, you can add an exemption to define different rules for a space. For example you may set the global retention rule to delete all page versions older than 2 years, but add an exemption for your Finance and HR spaces, so that all historical versions are kept. Alternatively you could set the global retention rule to keep all, and use exemptions to clean up particular spaces. 

You need system administrator global permissions to do this. 

To add an exemption for a space:

  1. Go to Administration  > General Configuration > Retention rules.
  2. Select Add exemption.
  3. Select a space.
  4. Under Page versions select Keep all, Keep by number, or Keep by age,  and then enter a value (if required).
  5. Under Attachment versions select Keep all, Keep by number, or Keep by age, and then enter a value (if required).
  6. Under Trash, select Keep all, or Keep by deleted date, and then enter a value (if required).
  7. Choose whether retention rules for this space can be managed by space administrators. 
  8. Save your changes.

The global retention rules will no longer apply to this space. 

Remove a space exemption

To remove an exemption:

  1. Go to Administration  > General Configuration > Retention rules.
  2. In the space exemptions list, locate your space and choose ... > Remove.

The global retention rules will now apply to this space.

List of spaces exemptions showing rules set for each space

Screenshot showing the global retention rules screen with exemptions listed for particular spaces.

Allow space administrators to manage exemptions

Often system administrators don't have detailed knowledge of the type of content that is stored in each space, so in big sites, it can be useful to allow space administrators to manage the retention rule exemptions for their spaces. 

To allow space administrators to manage retention rules:

  1. Go to Administration  > General Configuration > Retention rules.
  2. Select Edit under Global retention rules.
  3. Under Exemption permissions, select System administrators and space administrators.
  4. Save your change. 

This applies to all spaces, unless there is an exemption which sets different exemption permissions. 

To allow space administrators to manage retention rules for a specific space:

  1. Go to Administration  > General Configuration > Retention rules.
  2. Add or edit an existing Exemption 
  3. Under Exemption permissions, select either System administrators and space administrators.
  4. Save your change. 

Space administrators will be able to change the retention rules, as described below.  

View the retention rules in a space

Space administrators can always see the retention rules that apply to their space, even if they don't have permission to edit the rules. 

To view the retention rules in a particular space:

  1. Go to the space and select Space tools > Content Tools from the bottom of the sidebar
  2. Select the Retention rules tab.

Space administrators will only be able to edit the retention rules for their space if a system administrator has allowed space administrators to manage exemptions. 

Change the retention rules in a space

You need space admin space permissions to do this. The edit button will be disabled if your system administrator has not allowed space administrators to manage exemptions. 

To change the retention rules in a particular space:

  1. Go to the space and select Space tools > Content Tools from the bottom of the sidebar
  2. Select the Retention rules tab
  3. Select Edit.
  4. Select Use retention rules defined in this space from the Exemption permissions drop down.
  5. Under Page versions select Keep all, Keep by number, or Keep by age,  and then enter a value (if required).
  6. Under Attachment versions select Keep all, Keep by number, or Keep by age, and then enter a value (if required).
  7. Under Trash, select Keep all, or Keep by deleted date, and then enter a value (if required).
  8. Save your change. 

This will add an exemption for this space, or update the existing exemption, if one already exists. 

Revert back to global retention rules in a space

To revert back to the global retention rules in a particular space:

  1. Go to the space and select Space tools > Content Tools from the bottom of the sidebar
  2. Select the Retention rules tab.
  3. Select Edit.
  4. Select Inherit global retention rules from the Exemption permissions drop down.
  5. Save your change. 

This will remove the space exemption. 

Retention rules tab in space tools showing a user editing the retention rules

Screenshot showing a space administrator editing retention rules for a space 

Considerations for administrators

There are a few things you need to consider before changing the retention rules. 

Global retention rules apply to all spaces, including archived and personal spaces

The global retention rules apply to all spaces, including archived spaces and personal spaces.  If you want to avoid automatically deleting historical versions in archived spaces or personal spaces, you will need to use exemptions either to protect spaces that need to be preserved, or to target spaces that can be cleaned up.

Once you set a global rule, Confluence will start deleting items that don't meet that rule almost immediately, so make sure any exemptions are in place before setting a global rule. 

Deleted versions cannot be restored

Deleted versions do not go to the trash, and cannot be restored once deleted. If you need to retain data for regulatory or compliance reasons, you may want to only allow retention rules to be added and updated in the global administration, by system administrators. This is the default. 

As always, we recommend you have a robust backup strategy, and a plan for how you will restore data from your backups if required. 

Versions can increment very quickly

It's not unusual for many page or file versions to be created within a short space of time. 

  • A new version of a page is created each someone clicks Publish (or Save if you have collaborative editing disabled).
  • A new version of a file is created each time a file with the same name is attached to the page, or a new version uploaded via the Upload button in the preview.

You should factor this in when determining the rule criteria to use, so versions aren't deleted too aggressively. Deleting versions by date rather than number may be more appropriate. 

Versions are not renumbered and people who contributed to deleted versions will not be listed in page history 

The page history screen will show all remaining versions. Page versions that have been deleted, either by a user, or automatically, will not appear. This is intentional, to indicate that any earlier collaboration (including by the original page creator) is no longer available to view or restore.

See an example...

In this example version 6 was deleted manually by a user (1), and versions 3 and earlier (2) were deleted because they didn't meet the retention rule criteria. 


The page creator (shown in the byline) will still be the original page creator, and all previous contributors will be recognised if you search by contributor, but we don't list the people who contributed to versions that were deleted on the page history or attachments versions page. 


Last modified on Feb 21, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.