Using Retention Policies to Manage Content Deletion

Retention is available as a paid, add-on feature for Business Plus, Enterprise and Elite customers. 


Retention policies enable you to retain certain types of content in Box for a specified period of time,
and to remove content from Box that is no longer relevant.
Retention policies apply to all file versions.  That means when a retention policy is applied to a file, it applies to all existing versions of that file as well as to future versions of that file.  Here's an example:
  • Version 1 of a file has a 7-day retention period
  • Version 2 is uploaded 3 days later
The 7-day retention period applies to Version 2, but starts from when Version 2 was uploaded.  In other words, Version 2 will be retained for 7 days from the upload date -- 4 days after Version 1 would have been deleted.
Admins and Co-Admins (with explicit permission to manage policies) can create retention policies and can apply those policies at the global level, folder level, and file level.  This makes it easier to properly retain unstructured data and ensure regulatory mandates are met
Retention policies are available via the Admin Console, API, and Tier 1 SDKs.
In this topic:



Creating a Retention Policy

  1. Open the Admin Console.
  2. In the lefthand navigation, click Governance.
  3. Within the Retention tab, click Create Retention Policy

Using Retention Policies - create retention policy.png


  1. The Create Retention Policy screen displays.  Here you can specify the details of how you want this policy to function.

Using Retention Policies - retention, time, disposition.pngUsing Retention Policies - email, apply policy.png

  1. In the Retention Policy Name section, enter a name for your policy.
  2. In the Time Period section, specify the amount of time you need to retain the content, beginning from the date the content is uploaded or created in Box. Available retention periods are:
    • 30, 60, or 90 days
    • 1, 3, 6, or 10 years
    • A custom number of days or years
    • An indefinite period of time. 

Note   For files that must be retained for the life of a customer or the life of an enterprise, use an indefinite period of time. You can then update/edit the retention policy when you know when the files are eligible for disposition. 

  1. In the Disposition Action section, choose what you would like to do with the files after they have been retained for the specified time period.
    • To keep the files in their current location, choose None. Users with appropriate permissions will be able to delete these files after the retention period has been met.
    • To delete the content permanently once the retention period has ended, choose Permanently delete content. Folder owners and co-owners can still extend this deletion date if you have selected this option.
  1. In the Email Notifications section, choose which users should receive email notifications about the retention policy. Selected users will receive a weekly email with a list of folders that contain files whose retention policies are set to expire within 14 days.
    • You can choose to notify all Owners and Co-Owners of items that are being retained, or select specific managed users.
  1. In the Apply Policy To section, specify the content to which the retention policy should apply.
    • To retain content within a specific folder, select Content within specific folders.
    • To retain items with specific metadata templates or drop-down menu options, select Content with specific metadata.
    • To retain all content uploaded to Box while the policy is in place by selecting All new content

Note   This option does not apply to existing content in an enterprise -- only to new content uploaded to the enterprise once the policy has started.

  1. Click Next.
  2. Click Select Folders or Select Metadata (depending on which option you chose in the Apply Policy To section in the previous step). When you click the button, a dialog box displays in which you can make selections. 

Using Retention Policies - select folder.png


Note   If you click Select Metadata, only metadata templates or dropdown field options are available to select.  If you select multiple metadata templates or dropdown field options, then the retention policy applies to files containing any one of the selected items.

  1. When you are finished making selections in the dialog box, click Choose.
  2. Review the details for the selected items, then click Next.

Note   If an existing retention policy with equal or greater time period already exists on any of the selected items, the system prompts you either to remove the selection or to modify the Time Period in the previous step.

  1. Review your retention policy before you start it. Verify that all the information is correct.
    • To edit the policy, click Edit.
    • If everything looks good, click Start Policy to begin the retention policy.

Using Retention Policies - start policy.png


Editing a Retention Policy

After you create a retention policy, you can edit the policy.

IMPORTANT   After you create a policy you cannot edit the policy's Time Period, Policy Type, or Apply Policy To.

  1. To edit a retention policy, open the Admin Console.
  2. In the lefthand navigation, click Governance.
  3. Within the Retention tab, locate the policy you want to edit, and click on it.  The policy details screen displays.
  4. Next to the Retention Policy Details section,  click Edit.
  5. Making the changes you want, then click Save. Using Retention Policies - edit policy details.png  

Note   The time to apply the retention policy (both initially and for any new files) depends on the number of files affected by the retention policy.  In other words, the more objects you want retained (files), the longer it takes for the retention policy to become active.  To verify that your retention policy is in fact applied, in your admin console click Reports and then navigate to User Activity > Policies > Retention Policy Applied.

Retiring a Retention Policy

Retiring a retention policy means that any content already under that retention policy will continue to adhere to that policy, but any new content will not be subject to the policy
  1. To retire a retention policy, open the Admin Console. 
  2. In the lefthand navigation, click Governance.
  3. Within the Retention tab, navigate to the desired policy and click Retire Policy.

Note    Retiring a policy is permanent.  You cannot undo it. 



Retention Policy Reporting

As an Admin, you can generate a report on the creation, editing, and retiring of a policy (administrative actions). You can also report on the application of policies to files and the deletion of files as part of an end-of-policy Disposition Action. 
Admins (and co-admins with the proper permission) can report on any of these actions for up to 7 years after an action was taken. Box does not keep reports beyond 7 years so you must download and maintain reports for retention beyond this 7-year period.


For information on how to run a report on your policies in the Admin Console, see: How Do I Run Reports On Policies And Automations? 


How Retention Interacts with Trash

Box has the capability to include items in the trash in its search results.  This means Admins can search the trash of all users for key words and phrases, even if the files have been removed from the Admin's view (because they were put in the trash)Review Box's developer documentation for more information on searching trash via API:


Users can delete retained files by sending them to the Trash.  However, they cannot purge files from Trash until the files' retention period has ended.  Before that time, they can also restore files from Trash to their their original location.  If the original location has been deleted, they can choose a new folder in which to place the files after they have restored them.
Additionally, below is the feature prioritization for content deletion (from highest precedence to lowest).
  • Legal Hold
  • Trash (if set to either Nobody or Never Delete)
  • Retention Policy (with Disposition Action = Permanently Delete Content)
  • Trash (any other setting) 

Example:  If Trash is purged every 30 days, but a file is to be retained for 6 years, the file will not be purged from the user’s Trash until the retention period has ended -- in this case, for 6 years.


End User Experience

When a file is governed by a retention policy, an indicator displays in the righthand navigation under the Details section.  You also see this information by clicking the More options arrow to the right of the file name and then selecting Properties > General Info
For folder-based retention, certain actions can modify the retention policy associated to a file. 
  • If you move a file from a folder with a retention policy to a folder without a retention policy, the file is still governed under the initial retention policy
  • If a you move a file carrying a retention policy to a folder with the same Time Period, Box preserves both the Time Period and the original Disposition Action. 
  • If a you move a file carrying a retention policy to a folder with a different Time Period, the longer Time Period takes precedence over the shorter one.  
  • If the Time Period is changed from one finite value to another finite value (such as 3 years to 5 years), the file will be retained based on the upload date of the file to Box.
  • If the Time Period is changed from indefinite to a finite value, the file will be retained based on the date the Time Period was updated
  • You cannot transfer a file or folder with a retention policy outside of the enterprise.  You also cannot change the folder owner to an external party, or move an individual file to a folder owned by an external user.
For metadata-based retention, certain actions can modify the retention policy associated to a file. 
  • If you remove the custom metadata that is carrying a retention policy from a file, the file is still governed by the initial retention policy. 
  • If you update the custom metadata on a file to a new metadata value with the same Time Period, Box preserves both the Time Period and the original Disposition Action. 
  • If you update the custom metadata on a file to a new metadata value with a different Time Period, the longer Time Period takes precedence over the shorter one. 
    • If you change the Time Period from one finite value to another finite value (e.g. 3 years to 5 years), the file will be retained based on the upload date of the file to Box.
    • If you change the Time Period from indefinite to a finite value, the file will be retained based on the  date the Time Period was updated
  • You cannot transfer a file or folder with a retention policy outside of the enterprise.  You also cannot  change the folder owner to an external party, or move an individual file to a folder owned by an external user.
Finally, if more than one retention policy is actively applied to a file via folder-based retention, metadata-based retention, or both, then one with the longer Time Period takes precedence.
Version history
Revision #:
62 of 62
Last update:
‎09-18-2018 12:13 PM
Updated by:
Tags (1)