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.
On this page
- The problem
- Prep 1 · Legacy ID
- Prep 2 · Required fields
- Prep 3 · Profile and Role IDs
- Prep 4 · Is Active and emails
- Insert the Users
- Keep the user map
- Practice run
- Gotchas and FAQ
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.
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.
- In Object Manager, open User → Fields & Relationships → New.
- 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.
Know the required fields.
The legacy system almost never has all of these. You build them in the workbook.
| Field | Watch out for |
|---|---|
| Last Name, Email | Usually in the source |
| Alias | 8 characters max. First initial + last name works: jsmith |
| Username | Email format, and unique across every Salesforce org, not just yours |
| Profile ID | The Salesforce ID, not the profile name. The profile also has to match the user’s license |
| Time Zone, Locale, Language, Email Encoding | Data 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.
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:
- Export the Profile and UserRole objects with Data Loader (Name and Id).
- Paste them into the workbook.
- VLOOKUP each user’s profile and role name to its ID.
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.
Insert the Users.
Copy the finished rows into their own CSV and run a normal Data Loader insert on User.
- 1
Build the final CSV
Copy the prepped rows into something like
users-prepped.csv, with only the columns you’re loading. - 2
Insert on User
Open Data Loader, choose Insert and the User object, then select the CSV.
- 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.
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.
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.
The questions people ask.
Why load Users before everything else?
Can I use the profile name instead of the ID?
Is Role required?
Will my users get a welcome email?
Why did I get a duplicate username error?
How long can an alias be?
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 LinkedInOne 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 →