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.

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. 

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. 
 

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

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. 

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.

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. 

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.

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.