Field Audit Trail, a Briefing for ISVs
Lynn Cohen (@slcohen) enables ISV partners in the Healthcare and Finance industry verticals to build, distribute, and support awesome Salesforce1 apps.
Our customers in regulated industries, such as Health Care and Finance, rely on the security and reliability of the Salesforce.com platform as well as features that enable auditing of end user actions on data. We continue to innovate and provide new auditing capabilities that enable our customers to meet their compliance needs, for example:
- Platform Monitoring – GA, Winter ‘15
- Field Audit Trail – GA, Spring ‘15
- BigObject with Ability to Archive Data – Pilot, Summer ’15 (subject to Safe Harbor)
Field Audit Trail expands on platform Field History features for tracking changes that end users make to data. ISVs need to understand how to work with these new features to support their customers having compliance and governance needs:
- Field history retention policies
- Accessing archived field history records
- Impact of Field Audit Trail on packaging
Field Audit Trail Explained
Since Field Audit Trail builds upon Field History, let’s take a quick review of Field History:
- All Salesforce.com editions come with Field History out of the box, with up to 20 fields per object selected for tracking changes
- Tracked changes may be displayed in a related History list and are stored in a related object, <object>__history, for up to 18 months
Field History in Action for a custom object, Equipment__c:
Field Audit Trail gives you the ability to track 3x more fields in a Force.com production org and control how long those field history records are retained in the org before being archived to longer-term storage:
- Maximum time to retain field history records in production org is 18 months
- Overall maximum time to retain a field history record is 10 years
- Up to 60 fields per object may be selected for tracking changes
Configuring and Accessing Field Audit Trail
Org Level Setup
At an org level, Field Audit Trail is an add-on. ISVs should contact their Account Executive for information on pricing and enabling this feature in their customers’ orgs. For development purposes, ISVs should log a case with Partner Support in the Salesforce.com Partner Community to enable this feature in their Partner Development Edition orgs.
Object Level Setup
Once Field Audit Trail is enabled in an org, use the same approach as before for selecting up to 60 fields per object for history tracking (i.e. via Setup UI or Metadata API).
A Field History Retention policy is set for an object and must be accomplished through the Metadata API. These policies are specified as part of a custom or standard object’s metadata, and the following standard objects are currently supported: Accounts, Cases, Contacts, Leads, and Opportunities.
The following metadata snippet is for the Equipment__c custom object illustrated earlier:
…
</fields>
<historyRetentionPolicy>
<archiveAfterMonths>3</archiveAfterMonths>
<archiveRetentionYears>5</archiveRetentionYears>
<description>Equipment history retention policy</description>
<gracePeriodDays>0</gracePeriodDays>
</historyRetentionPolicy>
<label>Equipment</label>
…
Meaning of attributes:
- archiveAfterMonths is time to hold field history records in org
- archiveRetentionYears is total time to retain field history records
- gracePeriodDays only applies when the retention policy is defined, and it allows for a delay before the first archival is performed
Logical flow of field history data for Equipment__c object:
Accessing Archived Field History Data
Archived history records for all objects are accessible via a single, special object: FieldHistoryArchive. These records can be queried and accessed through the REST API, SOAP API, and SOQL queries. For example, the following query searches for archived field history for a particular Equipment__c record:
SELECT Field, Id, ParentId, NewValue, OldValue, FROM FieldHistoryArchive WHERE FieldHistoryType = ‘Equipment__c’ AND ParentId = ‘a01j0000004FBZi’
Considerations Related to Packaging
If you package a custom object that has a Field History Retention policy, that policy is also packaged. As an ISV, you will most likely not want to package retention policies because your package will have a dependency on Field Audit Trail and customers will not be able to install your package unless their org is enabled for Field Audit Trail. Further, each customer is most likely going to have their own unique data retention policies making it unnecessary for you to package pre-defined policies.
Instead, consider providing a configuration service to your customers or perhaps develop an administrative utility to enable your customers’ admins to setup retention policies themselves.
The ability to setup retention policies in the Salesforce Administrative Setup UI is on the roadmap for Field Audit Trail (subject to Safe Harbor).
Additional Resources
Field Audit Trail Implementation Guide
