HistoryRetentionPolicy

Represents the policy for archiving field history data. When you set a policy, you specify the number of months that you want to keep field history in Salesforce before archiving it. By default, when Field Audit Trail is enabled, all field history is retained.

This component is only available to users with the RetainFieldHistory permission.

Declarative Metadata File Suffix and Directory Location

Field history retention policies are defined as part of a standard or custom object. You can set field history retention policies for objects individually. See CustomObject for more information.

Version

Available in API version 31.0 and later.

Fields

Field Name	Field Type	Description
archiveAfterMonths	int	Required. The number of months that you want to keep field history data in Salesforce before archiving. You can set a minimum of 1 month and a maximum of 18 months. If you don't set a number, the default is 18 months. (That is, Salesforce maintains data for 18 months before archiving.)
archiveRetentionYears	int	Required. You can set a minimum of zero years, and a maximum of 10 years.
description	string	A text description for the history retention.
gracePeriodDays	int	The number of days of extra time after the archiveAfterMonths period before the data is archived. The gracePeriodDays interval applies only to the first time that the data is archived; because all the data is copied the first time, the operation can take longer than subsequent times when only the data that changed since the last archival operation is copied. The gracePeriodDays provides extra time for the administrator to prepare the organization before the initial archive operation. You can set a minimum of zero days and a maximum of 10 days. If no number is set, the default is 1 day.

Declarative Metadata Sample Definition

This sample shows the definition of a history retention policy for a custom object.

The archiveRetentionYears field is required, but its value is only advisory. Use it as a reminder for when you want to manually delete data from the archive. By default, field history data isn’t automatically deleted when Field Audit Trail is enabled.

Note

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
3   <historyRetentionPolicy>
4       <archiveAfterMonths>6</archiveAfterMonths>
5       <archiveRetentionYears>5</archiveRetentionYears>
6       <description>My field history retention</description>
7   </historyRetentionPolicy>
8
9...
10</CustomObject>

Metadata API Developer Guide

HistoryRetentionPolicy

Declarative Metadata File Suffix and Directory Location

Version

Fields

Declarative Metadata Sample Definition