Loading

How to Use an External ID Field to Set Audit Field Values When Inserting Records with Data Loader

Date de publication: Jul 7, 2026
Description

When a Salesforce org has the "Create Audit Fields" permission enabled, administrators can preserve historical record metadata — such as the original CreatedDate and CreatedById values — when importing records using Salesforce Data Loader. This is particularly useful when migrating data from a legacy system where maintaining an accurate audit trail is required.
To set audit field values during a Data Loader import, you must use an External ID field as the matching key during an Upsert operation. The External ID field (a custom Text field marked as unique and external) serves as the identifier that allows Data Loader to recognize a record as new rather than an update to an existing record. This approach lets you create new records while populating CreatedDate, CreatedById, LastModifiedDate, and LastModifiedById from your source data.
Requirements:

  • Your Salesforce org must have the "Create Audit Fields" permission enabled
  • The object must have a custom External ID field (Text type, unique, case-sensitive)
  • Your CSV file must contain new records only — existing records cannot be updated using this method
  • The CSV must include a unique value in the External ID column for each record
Résolution

Step 1 — Create an External ID Field on the Target Object
An External ID field is a custom Text field that is designated as unique and marked as the identifier from an external system. Follow these steps to create one:

  1. Navigate to Setup.
  2. Go to Fields under the desired object:
    1. In Lightning Experience: Object Manager tab > Object Name > Fields & Relationships
    2. In Salesforce Classic (Standard Objects): Customize > Object Name > Fields
    3. In Salesforce Classic (Custom Objects): Create > Objects > Object Name > Custom Fields & Relationships
  3. Click New.
  4. Select Text and click Next.
  5. Enter the field name and label.
  6. Select Unique: "Do not allow duplicate values." Then select "Treat 'ABC' and 'abc' as different values (case sensitive)."
  7. Select External ID: "Set this field as the unique record identifier from an external system."
  8. Click Next.
  9. Choose the profiles that can view this field.
  10. Click Next, choose the page layout, then click Save.

Step 2 — Prepare Your CSV File
Your CSV file must include:

  • A column for the External ID field, populated with a unique value for each record
  • Columns for the audit fields you want to set: CreatedDate, CreatedById, LastModifiedDate, LastModifiedById
  • Only new records — do not include records that already exist in Salesforce

Step 3 — Upsert Records Using Data Loader to Set Audit Fields

  1. Open Data Loader and log in to your Salesforce org.
  2. Click Upsert.
  3. Choose the desired object and select your CSV file, then click Next.
  4. From the dropdown, select the External ID field to use for matching.
  5. Click Next.
  6. Select Existing Mapping or Create or Edit a Map. Ensure you have mapped the audit system fields: CreatedDate, CreatedById, LastModifiedDate, and LastModifiedById.
  7. Click Next, then click Finish.
  8. Click Yes on the confirmation pop-up.

Important Notes:

  • Audit fields can only be set on record creation — if the CSV contains any existing records, the upsert fails with the error: "Unable to create/update fields: CreatedDate. Please check the security settings of this field and verify that it is read/write for your profile or permission set."
  • The "Create Audit Fields" permission must be enabled by Salesforce Support for most org types.
Numéro d’article de la base de connaissances

000383278

 
Chargement
Salesforce Help | Article