Field Audit Trail Implementation Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 20

DownloadField Audit Trail Implementation Guide
Open PDF In BrowserView PDF
Field Audit Trail Implementation
Guide
Salesforce, Spring ’17

@salesforcedocs
Last updated: March 10, 2017

© Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,

as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTS
FIELD AUDIT TRAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
EXAMPLES

........................................................3

METADATA API REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
HistoryRetentionPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

SOAP API REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
FieldHistoryArchive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

TOOLING API REFERENCE

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

HistoryRetentionJob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

SOQL REFERENCE

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

SOQL with Archived Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

INDEX

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

FIELD AUDIT TRAIL
Field Audit Trail lets you define a policy to retain archived field history data up to ten years,
independent of field history tracking. This feature helps you comply with industry regulations related
to audit capability and data retention.
Use Salesforce Metadata API to define a retention policy for your field history. Then use REST API,
SOAP API, and Tooling API to work with your archived data. For information about enabling Field
Audit Trail, contact your Salesforce representative.
Field history is copied from the History related list into the FieldHistoryArchive object
and then deleted from the History related list. You define one HistoryRetentionPolicy
for your related history lists, such as Account History, to specify Field Audit Trail retention policies
for the objects that you want to archive. You can then deploy the object by using the Metadata API
(Workbench or Force Migration Tool). You can update the retention policy on an object as often as
you like.
You can set field history retention policies on the following objects.

EDITIONS
Available in: Salesforce
Classic
Available in: Enterprise,
Performance, and
Unlimited Editions

USER PERMISSIONS
To specify a field history
retention policy:
• “Retain Field History”

• Accounts
• Cases
• Contacts
• Leads
• Opportunities
• Assets
• Entitlements
• Service Contracts
• Contract Line Items
• Solutions
• Products
• Price Books
• Custom objects with field history tracking enabled
Note: The HistoryRetentionPolicy is automatically set on the above objects, once Field Audit Trail is enabled. By
default, data is archived after 18 months in a production organization, after one month in a sandbox organization, and all archived
data is stored for 10 years.
You can include field history retention policies in managed and unmanaged packages.
The following fields can't be tracked.
• Formula, roll-up summary, or auto-number fields
• Created By and Last Modified By
• Expected Revenue field on opportunities
• Master Solution Title or the Master Solution Details fields on solutions
• Long text fields
• Multi-select fields

1

Field Audit Trail

After you define and deploy a Field Audit Trail policy, production data is migrated from related history lists such as Account History into
the FieldHistoryArchive object. The first copy writes the field history that’s defined by your policy to archive storage and
sometimes takes a long time. Subsequent copies transfer only the changes since the last copy and are much faster. A bounded set of
SOQL is available to query your archived data.
Note: For some time after the initial GA release, data might not be automatically deleted from the History related list and may
reside in both the FieldHistoryArchive object and in the History related list. Salesforce reserves the right to delete
archived data from the History related list in accordance with the customer-defined policy in future releases.
Note: If your organization has Field Audit Trail enabled, previously archived data isn't encrypted if you subsequently turn on
Platform Encryption. For example, your organization uses Field Audit Trail to define a data history retention policy for an account
field, such as the phone number field. After enabling Platform Encryption, you turn on encryption for that field, and phone number
data in the account is encrypted. New phone number records are encrypted as they are created, and previous updates to the
phone number field that are stored in the Account History related list are also encrypted. However, phone number history data
that is already archived in the FieldHistoryArchive object continues to be stored without encryption. If your organization
needs to encrypt previously archived data, contact Salesforce. We will encrypt and rearchive the stored field history data, then
delete the unencrypted archive.

2

EXAMPLES
Set Data Retention Policy for Field History
This example demonstrates how to set a field history data retention policy by using Metadata API. You need to edit the metadata only
if you want to override the default policy values (18 months of production storage and 10 years of archive storage). Setting data retention
policy involves creating a metadata package and deploying it. The package consists of a .zip file that contains an objects folder
with the XML that defines each object’s retention policy, and a project manifest that lists the objects and the API version to use.
Note: The first copy writes the entire field history that’s defined by your policy to archive storage and might take a long time.
Subsequent copies transfer only the changes since the last copy, and will be much faster.
1. 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, and the number of years that you want to retain field history in the archive. The following sample file
defines a policy of archiving the object after six months, and keeping the archives for five years.



6
5
My field history retention


AccountSource
...


The file name determines the object to which the policy is applied. For example, to apply the above policy to the Account object,
save the file as Account.object. For existing custom objects, this works the same way, with the file named after the custom
object. For example: myObject__c.object.
2. 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.



Account
Case
Contact
Lead
Opportunity

32.0


3. 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.

3

Examples

Note: This pilot doesn’t support deployment from sandbox to production environments.
That’s it! Your field history retention policy will go 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. You must specify the minimum required
fields when creating a new custom object. Here’s sample XML that creates an object and sets field history retention policy:


Deployed
true
just a test object with one field for eclipse ide testing

3
10
1
Transaction Line History


Comments__c
add your comments about this object here
This field contains comments made about this object

32000
true
LongTextArea
30




Text

MyFirstObjects
ReadWrite


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. Once you deploy the metadata changes, the new policy overwrites
the old one.
Note: To check the current data retention policy for any object, retrieve its metadata using Metadata API and look up the value
of HistoryRetentionPolicy.

4

Examples

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:
SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue FROM FieldHistoryArchive
WHERE FieldHistoryType = ‘Account’ AND ParentId=’906F000000

5

METADATA API REFERENCE
HistoryRetentionPolicy
Represents the policy for retaining field history data. By setting a policy, you can specify the number of months you want to maintain
field history in Salesforce, and the number of years that you want to retain field history in the archive.
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. The number of years that you want to retain data in the archive.
You can set a minimum of zero years, and a maximum of 10 years. If no
number is set, the default is 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 may 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.

6

Metadata API Reference

HistoryRetentionPolicy

Declarative Metadata Sample Definition
This sample shows the definition of a history retention policy for a custom object:



6
5
My field history retention


AccountSource
...


7

SOAP API REFERENCE
FieldHistoryArchive
Represents field history values for all objects that retain field history. FieldHistoryArchive is a BigObject, available only to users
with the “Retain Field History” permission. This object is available in API version 29.0 and later.
Each instance of the FieldHistoryArchive object represents a single change in the value of a field. FieldHistoryArchive
stores history for both standard and custom fields.
The Field field returns the name of the field unless the parent field or object is deleted, in which case it returns the field ID. You can
use the ID to retrieve the old field and object name from the FieldNameAfterArchival and ParentNameAfterArchival
fields, respectively.

Supported Calls
describeSObjects(), query()

Fields
Field Name

Details

ArchiveFieldName

Type
string
Properties
Nillable
Description
The name of the field at the time the data was archived. If the field name changed,
the name is sometimes not the same for all records related to a single field.

ArchiveParentName

Type
string
Properties
Nillable
Description
The name of the parent object at the time the data was archived. If the object
name changed, the name is sometimes not the same for all records related to a
single field.

ArchiveParentType

Type
string
Properties
Nillable

8

SOAP API Reference

Field Name

FieldHistoryArchive

Details
Description
The type of the field at the time the data was archived. If the field type changed,
the type is sometimes not the same for all records related to a single field.

ArchiveTimestamp

Type
dateTime
Properties
Nillable
Description
The date and time at which the data was archived.

CreatedById

Type
reference
Properties
Nillable
Description
The user ID of the user who created the original record.

CreatedDate

Type
dateTime
Properties
Nillable, Sort
Description
The date and time at which the original record was created.

Field

Type
picklist
Properties
Filter, Nillable, Restricted picklist
Description
The name of the field that was changed. If the field is deleted from the parent
object, the Field field contains the field ID instead.

FieldHistoryType

Type
picklist
Properties
Nillable, Sort, Restricted picklist
Description
The name of the object that contains the field history (for example, Account).

Id

Type
ID

9

SOAP API Reference

Field Name

FieldHistoryArchive

Details
Properties
Defaulted on create, Filter, idLookup
Description
The ID of the archived record. It’s useful to have a field’s ID for fields that you’ve
deleted. (Field names aren’t retained in history when you delete fields from
Salesforce.)

NewValue

Type
anyType
Properties
Nillable
Description
The new value of the modified field.

OldValue

Type
anyType
Properties
Nillable
Description
The previous value of the modified field.

ParentId

Type
reference
Properties
Filter, Nillable, Sort
Description
The ID of the object that contains the field (the parent object).

Usage
When sorting fields, order them as follows:
1. FieldHistoryType ASC
2. ParentID ASC
3. CreatedDate DESC

10

TOOLING API REFERENCE
HistoryRetentionJob
Represents the body of retained data from the archive, and the status of the archived data. Available in API version 29.0 or later.

Supported SOAP API Calls
describeSObjects(), query()

Supported REST API HTTP Methods
GET

Fields
Field Name

Details

DurationSeconds

Type
int
Properties
Filter, Group, Nillable, Sort
Description
How many seconds the field history retention job took to complete (whether
successful or not).

HistoryType

Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort
Description
The object type that contains the field history that you retained. Valid values for
standard objects are:
• Account
• Case
• Contact
• Leads
• Opportunity
For custom objects, use the object name.

11

Tooling API Reference

HistoryRetentionJob

Field Name

Details

NumberOfRowsRetained

Type
int
Properties
Filter, Group, Nillable, Sort
Description
The number of field history rows that a field history retention job has retained.

RetainOlderThanDate

Type
dateTime
Properties
Filter, Sort
Description
The date and time before which all field history data was retained.

StartDate

Type
dateTime
Properties
Filter, Nillable, Sort
Description
The start date of the field history retention job.

Status

Type
picklist
Properties
Filter, Group, Nillable, Restricted picklist, Sort
Description
Provides the status of the field history retention job. By default, the pilot feature
copies data to the archive, leaving a duplicate of the archived data in Salesforce.
Deletion of data from Salesforce after archiving is available upon request.
Status can include:
• CopyScheduled
• CopyRunning
• CopySucceeded
• CopyFailed
• CopyKilled
• NothingToArchive
• DeleteScheduled
• DeleteRunning
• DeleteSucceeded
• DeleteFailed

12

Tooling API Reference

Field Name

HistoryRetentionJob

Details
• DeleteKilled

13

SOQL REFERENCE
SOQL with Archived Data
You can use SOQL to query archived fields.
The allowed subset of SOQL commands lets you retrieve archived data for finer-grained processing. You can use the WHERE clause to
filter the query by specifying comparison expressions for the FieldHistoryType, ParentId, and CreatedDate fields, as
long as you specify them in that order. That is, if you filter by using ParentId or CreatedDate, you must also filter by using the
preceding fields. The final comparison expression in the query can use any one of the comparison operators =, <, >, <=, or >=. Any
other comparison expression can use only the = operator. You can’t use the != operator.
You can use the LIMIT clause to limit the number of returned results. If you don’t use the LIMIT clause, a maximum of 2,000 results
are returned. You can retrieve additional batches of results by using queryMore().
SELECT fieldList
FROM FieldHistoryArchive
[WHERE FieldHistoryType expression [AND ParentId expression[AND CreatedDate expression]]
]
[LIMIT rows]

Examples: Allowed Queries
Unfiltered
SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue FROM FieldHistoryArchive

Filtered on FieldHistoryType
SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue FROM FieldHistoryArchive
WHERE FieldHistoryType = ‘Account’

Filtered on FieldHistoryType and ParentId
SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue FROM FieldHistoryArchive
WHERE FieldHistoryType = ‘Account’ AND ParentId=’906F00000008unAIAQ’

Filtered on FieldHistoryType, ParentId, and CreatedDate
SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue FROM FieldHistoryArchive
WHERE FieldHistoryType = ‘Account” AND ParentId=’906F00000008unAIAQ’ AND CreatedDate
> LAST_MONTH

The following table describes the SOQL functions that are available for querying archived fields.
Note: All number fields that are returned from a SOQL query of archived objects are in standard notation, not scientific notation
as in the number fields in the entity history of standard objects.

14

SOQL Reference

SOQL with Archived Data

Table 1: SOQL Functions Available for Archived Fields
Functionality

Details

DATE LITERALS

yesterday, last_week, and so on

LIMIT
WHERE

Filtering only on FieldHistoryType, ParentId, and
CreatedDate

15

INDEX
C

HistoryRetentionPolicy component 6

Components
HistoryRetentionPolicy 6

O
Objects
FieldHistoryArchive 8
HistoryRetentionJob 11

E
Example 3

S

F

SOQL
Supported by Field Audit Trail 14

Field Audit Trail 1
Field History 1
FieldHistoryArchive object 8

W
Workflow 3

H
HistoryRetentionJob object 11

16



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Create Date                     : 2017:03:11 06:40:29Z
Author                          : salesforce.com, inc.
Date Time Generated             : 2017-03-10T22:40:24.996-08:00
Trapped                         : False
DRC                             : 206.14
Modify Date                     : 2017:03:11 06:40:29Z
Format                          : application/pdf
Title                           : Field Audit Trail Implementation Guide
Creator                         : salesforce.com, inc.
Producer                        : XEP 4.20 build 20120720
Creator Tool                    : Unknown
Page Count                      : 20
Page Mode                       : UseOutlines
EXIF Metadata provided by EXIF.tools

Navigation menu