How to use the Salesforce Data Loader

Salesforce data loader upsert
Salesforce Data Loader Home Screen

Ever had spreadsheets of data that you’d love to have in Salesforce? In this post we run through how to use the Salesforce Data Loader to do just that. There are a number of ways to get your data into Salesforce, including:

Of these options, Data loader is the most flexible and appropriate for importing large data sets. Please note: the flexibility and power of this tool can lead to some highly complex import processes, so if you’re unsure whether you have the correct data migration plan for your production org, make sure you validate your plan with a Salesforce Implementation Partner.

Data Loader Installation and Setup Instructions

Before we start, you’ll need to install the data loader application on your computer. After you get your Salesforce org (click here to learn how to sign up for a CPQ and Billing developer Org), navigate to the setup section of your org and type ‘Data’ in the quick find box in the top left. When ‘Data Loader’ appears in the search results in the left sidebar, give it a click.

Download Salesforce Data Loader

Choose the download that applies for your the operating system your computer runs on and run through the installation wizard. If you’re running Windows, you may need to download Java.

Download Salesforce Data Loader for Windows

Prepare your data for import


You’ll likely need to transform your data from your source data to something that can be imported into Salesforce:

  • You’ll need to export your files to a CSV file format for Data Loader to be able to read it
  • If the objects you’re importing data into have multiple record types, you’ll need to include the record type Id for each row
  • If the objects you’re importing data into have parent records, you may need to include the parent record Id in your sheet to preserve the relationships
  • If you’re importing dates, you’ll need to format the dates as YYYY-MM-DD
  • It’s recommended to use a unique key from your source to identify the record you’re uploading to Salesforce, as each record will get its own Salesforce Id as it’s uploaded. If Salesforce doesn’t know a record already exists via this key, it won’t prevent the duplicate record from being created.

Record Ids are 15 character Ids that represent unique records between Salesforce org.

Record Type Ids

Be careful when working with record type Ids in your Sandboxes and your Production environment. An object’s record type names may be the same between different environments, however their record type Ids will always be different. Ensure that the record type Ids for the relevant objects in each org are correct before you upload or you’ll get errors.

To find these record type Ids, you can

  • Log into the relevant org
  • Navigate to the object manager in setup
  • Select the object
  • Under record types, select the relevant record type
  • The record type Id will be in the URL for the record type detail page

Depending on how the data is structured in your source system, you may need to break the source data into multiple spreadsheets to maintain the appropriate relationality in Salesforce. I find it useful to draw out a schema of how I want the data to appear in Salesforce, and each object will have its own CSV import file. I’ll go into more detail around this relational import later.

Loading your Data using Data Loader


Now you’re ready to start uploading your base data set, start Data loader and choose ‘Upsert’. For these records we can use our unique external Id fields to find if the record already exists in the system and update it, or insert the record if it doesn’t already exist.

Import data using Salesforce Data Loader

You’ll be taken to an authentication page. Make sure you use the login details of the correct org, and select ‘Production’ only when you’re doing a production migration.

Once you’ve given Data Loader access to your org’s data, choose the object you want to load your data to. Some objects are hidden by default, so if you don’t see the object in the default list, you may need to check ‘Show all Salesforce objects’.

data loader show all salesforce objects

Click browse to choose the CSV file you want to upload, and click next.

You’ll be able to choose the unique external field you want to upsert on. On some objects you may have multiple external Ids, and some may not be unique, so double-check your fields just to be safe.

On the following page, you can choose the parent object foreign keys. Here we can use external Ids again, on our parent object. They’ll be available via the lookup fields available to your uploading object. In order for values in these foreign key columns to be accepted for import, the parent record needs to be present, or else you’ll get an error.

Column – Field Mapping

On the next page you can map the columns of your CSV file to the relevant fields on your object in Salesforce. If you’re using foreign keys to relate this object to a parent, you’ll need to make sure that the CSV column containing the Id has the format {parentObjectLookupName}__r.{parentObjectIdFieldName}.

On the next page, select where you want to store your success and failure logs. These will come in handy later.

Click Finish to start loading your data. If you get errors, open the failure log and remedy the issues in the CSV upload file and retry. It’ll likely take you a few retries on your first time.

One of the common errors with importing is validation errors so you may need to deactivate these in order to complete your imports.

If everything’s been mapped and formatted properly, you wont get any errors. Congratulations!

Import Order

The import order you need to follow will follow from the relationships between the objects you’re importing. It’s easiest to think of this import order as a pyramid: the object that doesn’t have any parent objects gets imported first, then it’s children, then their children, and so on.

I hope this post has help you upskill around how to use the Salesforce Data Loader. Let me know what you think of the post in the comments.

Leave a Reply