Data Loader · Users

Users go first. Every Owner, Created By and Last Modified By in every later file points at one. Load them cleanly, keep the Legacy ID map, and the rest of the migration has something to hold on to.

Load firstEvery later object looks up Users
8 charactersmaximum for a user Alias
Globally uniqueUsernames, across every Salesforce org
19‑minute videoThe full walkthrough with the workbook
On this page
  1. The problem
  2. Prep 1 · Legacy ID
  3. Prep 2 · Required fields
  4. Prep 3 · Profile and Role IDs
  5. Prep 4 · Is Active and emails
  6. Insert the Users
  7. Keep the user map
  8. Practice run
  9. Gotchas and FAQ
Watch on YouTube ↗
The problem

Every other object points at a User.

Owner, Created By, Last Modified By: half the lookups in a migration are Users. Load them first, keep the map, and every later load gets easier.

If the Users aren’t in Salesforce yet, every Account, Contact and Opportunity you load lands with you as the owner, and the historical Created By is gone. So Users go first, and the most valuable thing you get out of the load isn’t the Users themselves. It’s the map from each old system’s user ID to the new Salesforce User ID.

Prefer to read? Everything in the video is written out below.

Prep 1

Add a Legacy ID field to User.

A Text field marked as an External ID holds the old system’s user ID. Every later load matches owners against it.

  1. In Object Manager, open User → Fields & Relationships → New.
  2. Choose Text, name it Legacy ID, and tick External ID.

That’s what lets an Account file say Owner:User-LegacyId__c instead of looking up Salesforce IDs by hand. More on External ID fields in a migration.

Prep 2

Know the required fields.

The legacy system almost never has all of these. You build them in the workbook.

FieldWatch out for
Last Name, EmailUsually in the source
Alias8 characters max. First initial + last name works: jsmith
UsernameEmail format, and unique across every Salesforce org, not just yours
Profile IDThe Salesforce ID, not the profile name. The profile also has to match the user’s license
Time Zone, Locale, Language, Email EncodingData Loader wants the underlying values, not the labels you see in the UI

Role looks required in some screens but isn’t. If the org hasn’t designed its roles yet, leave it blank and assign roles later.

Shortcut: create one user by hand, export it with Data Loader, and you have a real example of every value Salesforce expects. The workbook from the video already has tabs of accepted Time Zone, Locale, Language, Currency and Email Encoding values.

Prep 3

Swap Profile and Role names for IDs.

Your source says “Sales Manager”. Data Loader needs 00e….

For a handful of users, open each Profile or Role in Setup and copy the ID from the URL. For more than a handful:

  1. Export the Profile and UserRole objects with Data Loader (Name and Id).
  2. Paste them into the workbook.
  3. VLOOKUP each user’s profile and role name to its ID.
Prep 4

Decide on Is Active and emails.

Leave Is Active blank and every user loads active, which can run you out of licenses mid-load.

  • Is Active: blank means active. If licenses are tight, load users as inactive (FALSE) and activate them when they actually need to log in.
  • Welcome emails: Data Loader doesn’t offer “Generate new password and notify user immediately”. Inserting users this way doesn’t send them the new-user email, so plan how they’ll get access.
The load

Insert the Users.

Copy the finished rows into their own CSV and run a normal Data Loader insert on User.

  1. 1

    Build the final CSV

    Copy the prepped rows into something like users-prepped.csv, with only the columns you’re loading.

  2. 2

    Insert on User

    Open Data Loader, choose Insert and the User object, then select the CSV.

  3. 3

    Check the mapping

    Required fields mapped, Profile and Role ID columns going to the ID fields, Legacy ID going to your External ID field. Then run it.

Got errors back? DUPLICATE_USERNAME is the usual one. See the common Data Loader error codes.

After the load

Keep the user map.

The success file is the Legacy ID → Salesforce User ID map every later object depends on.

Rename the success file (something like user success) and paste it into its own tab in the workbook. From now on, Account, Contact, Opportunity and Activity loads can map Owner and Created By either through the Legacy ID lookup or with a VLOOKUP against this tab. The Accounts post shows both.

Practice

Run it in a Developer Org first.

Prep, map, insert, verify, on test data, before you go near a real org.

Load the practice file in a free Developer Org and work through every step. One trap with test data: usernames like example.user@test.com are probably already taken in some other org somewhere, and Salesforce will reject them. Add something unique, like @yourname-test.com, before you load.

Gotchas

The questions people ask.

Why load Users before everything else?
Because Owner, Created By and other user lookups on every later object need the Users to exist, and the Legacy ID map makes those lookups possible.
Can I use the profile name instead of the ID?
No. Data Loader needs the Profile ID. Export Profiles and VLOOKUP the names to IDs.
Is Role required?
No. It can look that way in the UI, but you can insert Users without one.
Will my users get a welcome email?
Not from a Data Loader insert. Plan password resets or SSO separately.
Why did I get a duplicate username error?
Usernames are unique across every Salesforce org. Change the username, even in a sandbox or Developer Org.
How long can an alias be?
Eight characters.
Data Migration Masterclass

Users are step one of forty.

The Masterclass walks through the whole migration in load order, with the workbooks I use on real projects, including this one.

Know someone about to load Users for a migration?

Share on LinkedIn
Doing this for a whole org, not just one object?

One CSV is a tutorial. Forty objects, 15 years of history and a go-live date is a project. That’s the part I do for a living.

See how I run migrations →