SfSkills Domains Docs GitHub

Home / security / field-audit-trail

field-audit-trail

Salesforce Shield Field Audit Trail: configuration, retention policies, querying archived field data, compliance requirements. NOT for field history tracking (use field-history-tracking) — use data/field-history-tracking.

Open the skill folder on GitHub

Field Audit Trail

This skill activates when a practitioner needs to configure Salesforce Shield Field Audit Trail (FAT) for long-term field-change retention, query archived field history via FieldHistoryArchive, or map compliance regulations (FINRA, HIPAA, GDPR, SOX) to FAT retention policies. It does NOT cover standard Field History Tracking — use the field-history-tracking skill for that.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

What Field Audit Trail Is

Field Audit Trail is a Salesforce Shield feature that extends field-change history retention far beyond the standard 18-month limit of Field History Tracking. With FAT enabled and a retention policy set, field change data is archived into the FieldHistoryArchive sObject, which persists for the configured retention period — up to 10 years.

FAT captures: who changed a field, when, from what value, to what value — the same data as standard field history. The key difference is the storage backend and retention duration. Data older than the standard window migrates asynchronously to FieldHistoryArchive.

FAT is configured entirely through Setup (no code required for enabling it), but querying archived data requires SOQL against FieldHistoryArchive.

How FAT Differs from Standard Field History Tracking

DimensionField History TrackingField Audit Trail
LicenseIncluded in all editionsRequires Salesforce Shield
RetentionUp to 18 months (rolling)Up to 10 years (configurable)
Max fields per object2060
Storage locationStandard History sObjects (e.g., AccountHistory)FieldHistoryArchive sObject
Query mechanismStandard SOQL on History sObjectsSOQL on FieldHistoryArchive
ReportsYes — History sObjects are reportableNo — FieldHistoryArchive is not available in Reports
SetupField History Tracking checkbox per objectSeparate FAT policy per object in Setup > Field Audit Trail
Async archivalN/AYes — data migrates to archive asynchronously

Both can be active simultaneously. Standard history records remain in XxxHistory objects for their normal window; older records move to FieldHistoryArchive.

Retention Policies

A FAT retention policy defines how long archived field history is kept for a given object. Policies are set in Setup > Field Audit Trail. You specify the object and the retention period (in months, up to 120 — 10 years). Salesforce also defines a deletion period that controls how long after the retention period data is actually purged.

Retention policies are per object. Different objects can have different retention periods. If no custom policy is set, a default policy applies (Salesforce determines the default; always verify this against your compliance requirement and set an explicit policy).

FieldHistoryArchive Object and Querying

FieldHistoryArchive is a read-only platform sObject available only to orgs with Shield. It stores archived field change records for all FAT-enabled objects in a unified table, distinguished by the SobjectType field.

Key fields on FieldHistoryArchive:

FieldDescription
SobjectTypeAPI name of the tracked object (e.g., "Account")
FieldHistoryTypeCompound value identifying the tracked field (e.g., "AccountAnnualRevenue")
ParentIdId of the record that was changed
OldValueValue before the change
NewValueValue after the change
CreatedByIdUser who made the change
CreatedDateTimestamp of the change

Query example — retrieving archived history for a specific Account:

SELECT ParentId, FieldHistoryType, OldValue, NewValue, CreatedById, CreatedDate
FROM FieldHistoryArchive
WHERE SobjectType = 'Account'
  AND ParentId = '001XXXXXXXXXXXX'
ORDER BY CreatedDate DESC
LIMIT 200

Query example — retrieving archived history for a specific field across all records:

SELECT ParentId, OldValue, NewValue, CreatedById, CreatedDate
FROM FieldHistoryArchive
WHERE SobjectType = 'Contact'
  AND FieldHistoryType = 'ContactAnnualRevenue__c'
  AND CreatedDate >= 2022-01-01T00:00:00Z
ORDER BY CreatedDate ASC

SOQL limitations on FieldHistoryArchive: Not all fields are indexed for filtering. Filtering on ParentId and CreatedDate is efficient; filtering on OldValue or NewValue with a WHERE clause is an unindexed scan and will time out on large archives. Always anchor queries with ParentId or a bounded CreatedDate range.

Common Patterns

Pattern: Enabling FAT on High-Sensitivity Fields for Regulatory Compliance

When to use: The org must demonstrate to auditors (FINRA, HIPAA, SOX, GDPR) which users changed specific sensitive fields and when, over a multi-year period.

How it works:

  1. Confirm Shield license is active.
  2. Go to Setup > Field Audit Trail.
  3. Select the target object (e.g., Account, Contact).
  4. Enable tracking for the required fields (up to 60 per object).
  5. Set the retention policy to match the compliance requirement (e.g., 84 months for FINRA's 7-year requirement).
  6. Save the policy. Existing history already in the standard History sObject will migrate to FieldHistoryArchive asynchronously over the next several days.
  7. Validate by querying FieldHistoryArchive after migration completes.

Why not Field History Tracking alone: Standard Field History Tracking caps at 18 months. For FINRA's 7-year requirement or HIPAA's 6-year PHI access log requirement, standard tracking is insufficient and creates compliance gaps.

Pattern: Querying FieldHistoryArchive for Audit Evidence

When to use: Compliance team or legal counsel requires a point-in-time record of changes to a specific record or field set, pulled programmatically for an audit response.

How it works:

Use a bounded SOQL query filtered first on SobjectType and ParentId (or a CreatedDate range), then process results in Apex or an external tool:

List<FieldHistoryArchive> archived = [
    SELECT ParentId, FieldHistoryType, OldValue, NewValue,
           CreatedById, CreatedDate
    FROM FieldHistoryArchive
    WHERE SobjectType = 'Opportunity'
      AND ParentId IN :opportunityIds
      AND CreatedDate >= :startDate
      AND CreatedDate <= :endDate
    ORDER BY CreatedDate ASC
    LIMIT 50000
];

Export to CSV or a Big Object for offline audit delivery. Because FieldHistoryArchive is not reportable, the only way to extract data for auditors is via SOQL (Apex, Data Loader, or Workbench).

Why not use Reports: FieldHistoryArchive is intentionally excluded from the Report Builder. Attempting to create a report against it will fail.

Pattern: Combining Standard History and FieldHistoryArchive in a Single View

When to use: The org needs a complete timeline of changes — including recent changes (in the standard History sObject) and older changes (in FieldHistoryArchive) — for audit or analytics purposes.

How it works:

Query both AccountHistory (or the relevant History sObject) and FieldHistoryArchive separately, then merge and sort the results in Apex or the calling application:

// Recent history (standard)
List<AccountHistory> recent = [
    SELECT Field, OldValue, NewValue, CreatedById, CreatedDate
    FROM AccountHistory
    WHERE AccountId = :recordId
    ORDER BY CreatedDate DESC
];

// Archived history (FAT)
List<FieldHistoryArchive> archived = [
    SELECT FieldHistoryType, OldValue, NewValue, CreatedById, CreatedDate
    FROM FieldHistoryArchive
    WHERE SobjectType = 'Account'
      AND ParentId = :recordId
    ORDER BY CreatedDate DESC
];

Merge both result sets by CreatedDate in the calling layer. Deduplicate records that appear in both (overlap can occur during the migration window).

Decision Guidance

SituationRecommended ApproachReason
Retention needed for 18 months or lessStandard Field History TrackingNo Shield required; fully reportable
Retention needed for 2–10 yearsShield Field Audit Trail with explicit retention policyOnly FAT supports multi-year retention
Need to query archived field changes programmaticallySOQL against FieldHistoryArchiveOnly supported query mechanism for archived data
Need to build a report showing historical field changesQuery XxxHistory sObjects (not FAT) or export via SOQLFieldHistoryArchive is not in Report Builder
More than 20 fields need long-term tracking on one objectShield FAT — up to 60 fields per objectStandard FHT hard-caps at 20 fields
Need to track a field not yet in Field History TrackingEnable Field History Tracking AND FAT for that fieldBoth must be enabled for the field to be captured
Compliance regulation requires 7-year retention (FINRA)FAT retention policy set to 84 monthsMatches FINRA Rule 17a-4 requirement
PHI access log retention under HIPAAFAT retention policy set to at least 72 monthsHIPAA requires 6-year retention for access logs

Step-by-step instructions for an AI agent or practitioner activating this skill:

  1. Gather context — confirm the org edition, relevant objects, and current configuration state
  2. Review official sources — check the references in this skill's well-architected.md before making changes
  3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
  4. Validate — run the skill's checker script and verify against the Review Checklist below
  5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking FAT configuration work complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Field History Tracking is still required alongside FAT — Enabling FAT does not automatically capture field changes. Field History Tracking must also be enabled on the same object and fields. FAT extends retention of the data that Field History Tracking captures; it is not a standalone capture mechanism. Missing this step means FAT policies are active but no data flows into the archive.
  2. Standard field history is still capped at 20 fields even with Shield — Standard Field History Tracking remains limited to 20 fields per object even when FAT is licensed. FAT raises the ceiling to 60 fields, but only for the FAT-tracked fields; the standard 20-field limit still governs the non-FAT history window. In practice, plan field selection carefully to stay under 60 total for FAT.
  3. FieldHistoryArchive is not available in Reports or List Views — Compliance teams that expect to build Salesforce Reports against archived data will be blocked. The only supported query mechanism is SOQL (Apex, Data Loader, Workbench, or external ETL). Plan for a SOQL-based audit extraction workflow.
  4. Archival is asynchronous — timing is not guaranteed — When FAT is enabled or when existing records fall outside the standard retention window, migration to FieldHistoryArchive happens asynchronously in the background. There is no user-visible indicator of when migration completes. Do not perform compliance audits immediately after enabling FAT; allow several days for the backfill.
  5. Non-indexed field filters on FieldHistoryArchive cause query timeouts — Filtering FieldHistoryArchive on OldValue, NewValue, or FieldHistoryType alone (without bounding on ParentId or CreatedDate) will trigger full-table scans on potentially billions of rows. Always include ParentId or a tight CreatedDate range as the primary filter. Salesforce may enforce query governor limits or time out the query with no result.

Output Artifacts

ArtifactDescription
FAT retention policy decisionsPer-object table mapping compliance regulation to required retention months and FAT policy settings
FieldHistoryArchive SOQL query setParameterized queries for audit extraction by record, field, date range
Compliance evidence matrixMapping of regulations (FINRA, HIPAA, GDPR, SOX) to specific tracked objects and fields
FAT activation checklistStep-by-step enablement verification record

Package files