Examples

Here are some examples of field history workflows.

Set Data Retention Policy for Field History

This example demonstrates how to set a field history data retention policy using Metadata API. By default, field history data is not automatically deleted. Edit the metadata only if you want to override the default policy values of 18 months of production storage. Setting a data retention policy involves creating a metadata package and deploying it. The package consists of a .zip file and a project manifest that lists the objects and the API version to use. The .zip file contains an objects folder with the XML that defines each object’s retention policy.

The first copy writes the entire field history that’s defined by your policy to archive storage and takes a long time. Subsequent copies transfer only the changes since the last copy, and are faster.

Note

Define a field history data retention policy for each object. The policy specifies the number of months that you want to maintain field history in Salesforce. The following sample file defines a policy of archiving the object after six months.
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>
The file name determines the object to which the policy is applied. For example, to apply the preceding policy to the Account object, save the file as Account.object. For existing custom objects, the file is also named after the custom object. For example: myObject__c.object.

Create the project manifest, which is an XML file that’s called package.xml. The following sample file lists several objects for which data retention policy is to be applied. With this manifest file, you expect the objects folder to contain five files: Account.object, Case.object, and so on.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>Account</members>
5        <members>Case</members>
6        <members>Contact</members>
7        <members>Lead</members>
8        <members>Opportunity</members>
9        <name>CustomObject</name>
10    </types>
11    <version>45.0</version>
12</Package>

Create the .zip file and use the deploy() function to deploy your changes to your production environment. For more information, see the Metadata API Guide.

This feature doesn’t support deployment from sandbox to production environments.
Note

That’s it! Your field history retention policy goes into effect according to the time periods that you set.

Create a Custom Object and Set Field History Retention Policy at the Same Time

You can use Metadata API to create a custom object and set retention policy at the same time. Specify the minimum required fields when creating a custom object. This sample XML creates an object and sets field history retention policy.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
3    <deploymentStatus>Deployed</deploymentStatus>
4    <enableHistory>true</enableHistory>
5    <description>just a test object with one field for eclipse ide testing</description>
6    <historyRetentionPolicy>
7        <archiveAfterMonths>3</archiveAfterMonths>
8        <archiveRetentionYears>10</archiveRetentionYears>
9        <gracePeriodDays>1</gracePeriodDays>
10        <description>Transaction Line History</description>
11    </historyRetentionPolicy>
12    <fields>
13        <fullName>Comments__c</fullName>
14        <description>add your comments about this object here</description>
15        <inlineHelpText>This field contains comments made about this object</inlineHelpText>
16        <label>Comments</label>
17        <length>32000</length>
18        <trackHistory>true</trackHistory>
19        <type>LongTextArea</type>
20        <visibleLines>30</visibleLines>
21    </fields>
22    <label>MyFirstObject</label>
23    <nameField>
24        <label>MyFirstObject Name</label>
25        <type>Text</type>
26    </nameField>
27    <pluralLabel>MyFirstObjects</pluralLabel>
28    <sharingModel>ReadWrite</sharingModel>
29</CustomObject>

Set trackHistory to true on the fields that you want to track and false on the other fields.

Update Data Retention Policy for Field History

If a field history data retention policy is already defined on an object, you can update the policy by specifying a new value of HistoryRetentionPolicy in the metadata for that object. When you deploy the metadata changes, the new policy overwrites the previous one.

To check the current data retention policy for any object, retrieve its metadata using Metadata API and look up the value of HistoryRetentionPolicy.

Note

Query Archived Data

You can retrieve archived data by making SOQL queries on the FieldHistoryArchive object. You can filter on the FieldHistoryType, ParentId, and CreatedDate fields, as long as you specify them in that order. For example:

1SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue FROM FieldHistoryArchive WHERE FieldHistoryType = 'Account' AND ParentId='001D000000INjVe'