Loading Salesforce Users

The most common task of any Salesforce implementation is the creation of user accounts. All projects need users! It can be as simple as inputting a few users from the UI or loading one or several CSV files dealing with parent-child relationships. "Users" have a particular place in Salesforce between metadata and real data. In this post, I'm going to talk about "Users" import and configuration in an org where you've already deployed the security components "Profiles", "Permission Sets", "Roles", "Public Groups" and "Queues".

Preparing Your Toolbox

Before starting your journey into users import, you need to make sure you've got the right tools and approach to do the job.

File Format

📃 The usual format used during data migrations is CSV. It's a simple text structure, easy to manipulate but not very robust. My recommendation is to learn a method which (1) works for you and (2) deal with all use cases. This way, you won't have to reinvent the wheel project after project.

In particular, I suggest to always stick to UTF-8 for character encoding. Even if you're not working on an international double-bytes project you may get a couple of foreign last names lost in the bulk of your data that caries accented characters from Western or Eastern Europe.

Character Codes

✏️ When editing CSV files I use Easy CSV Editor on my Mac and Ron's Editor on my PC. Sometimes a text editor, like VS Code, for instance, can be handy to access raw data, validate delimiters and the general shape of a file. If you're not sure, you can use the online service csvlint. Ban the use of traditional spreadsheets ("Excel" or "Numbers") as it's difficult to control how the data is actually saved to disk. Instead, prefer database apps like "Access" or my Salesforce Users Import Template.


🤖 There are two APIs available to load data in Salesforce. The traditional SOAP and the more recent Bulk API. I yet have to find a clear use case for SOAP. Bulk might be a bit touchy at times, especially when dealing with files, but there are some settings to tune the Bulk API. So, I have configured all my data migration tools to use the Bulk API.

🛠️ At some point in the process, you'll have to identify fields by their API names. I recommend using the Chrome Extension Salesforce Inspector for this purpose. And for when you need to look around in the database, nothing beats the Salesforce professional's Swiss army knife: The Workbench.

Data Loader

🚛 To load your data in a Salesforce server, you need a client app. Here is a short list of the free options on the table. I'm not evaluating the paid options as they're not a fit for consultants. Expect the below results to change drastically when paying for the service.

This is the reference to which all tools are measured. It's provided and supported by Salesforce which is a key advantage. It's got a comprehensive list of tuning options and is very robust. When an insert is timing-out with another tool, I always end up trying with the Salesforce Dataloader. The main issue I have with it, is that it's not convenient to use when running many transactions, redoing stuff, changing org... You're always starting from scratch.

Good Average Bad
Install ✔️
Performance ✔️
Resilience ✔️
Ease of use ✔️
Tuning ✔️
Support ✔️
Roadmap ✔️

Dataloader.io is well known for dealing with parent/child lookups from within the field mapping section. Which means that there's no need to retrieve Salesforce IDs before loading records containing parent lookups! It's also very easy to use, thanks to its slick UI. And that's also its default, there's not much to configure should you want to tune a data load. Also, there's no support which can become a blocker when you need it.

Good Average Bad
Install ✔️
Performance ✔️
Resilience ✔️
Ease of use ✔️
Tuning ✔️
Support ✔️
Roadmap ✔️

Jitterbit feels like a data loader created by people who are used to load data! With one login to your Jitterbit account to get access to all the salesforce orgs you're working on. You can create a library of queries, run multiple queries in parallel, run the same query on multiple orgs and do some clever transformations. The support is done via a community forum where questions usually get a quick answer. The setup process can be tricky though and the last update was released in Decembre 2016.

Good Average Bad
Install ✔️
Performance ✔️
Resilience ✔️
Ease of use ✔️
Tuning ✔️
Support ✔️
Roadmap ✔️

So, in the end, Jitterbit is my weapon of choice and I keep Salesforce Dataloader as a backup tool.
From time to time, I log on Dataloader.io and check if it's any better. It has the potential to become the best option but it's not there yet and I hope that Salesforce's acquisition of Mulesoft will help the product in this respect.

Getting Organised

There's a logical order to go through the migration.

  1. Deploy the metadata to the target org (including security components).
  2. Retrieve the security components IDs.
  3. Import the users using the "Profiles" and "Roles" IDs.
  4. Retrieve the user IDs from the success log.
  5. Load the assignment junction objects.

Loading Method

At this point, you're ready to complete the data migration using the "Users" and "Queues" IDs to set records ownership.

Retrieving The Security Components IDs

Although "Profiles", "Permission Sets", "Roles", "Public Groups" and "Queues" can be migrated as data, you're better-off deploying them as metadata. So, assuming they've already been deployed when the users migration starts, the first thing to do is to retrieve their IDs. The following SOQL queries will do just that.

-- Profiles
SELECT Name, Id FROM Profile

-- Roles
SELECT Name, Id FROM UserRole

--Permission Set
SELECT Name, Id FROM PermissionSet WHERE IsOwnedByProfile = FALSE

-- Groups
SELECT Name, Id FROM Group WHERE Type = 'Regular'

-- Queues
SELECT Name, Id FROM Group WHERE Type = 'Queue'

Store the results in the tabs starting with "IDs" of my Salesforce Users Import Template.

Tabs IDs

Importing The Users

There is multiple information to gather for this part of the process:

  • The users' data that the business owner wants to import.
  • The users' data that Salesforce considers mandatory.
  • The many-to-many relationship between users and their "Permission Sets", "Public Groups" and "Queues" membership.

😱 This may look like a simple task but it tends to be a pain. It usually requires multiple back and forth between the business owner and yourself, juggling with several versions of an Excel file.

As I needed a smoother workflow, I came-up with the process I'm sharing in this post and which is based on a Google Sheet. In a nutshell, both tabs and columns headers follow the same colour code:

  • Blue: for the business owner and yourself if you can help.
  • Yellow: comments that are not imported.
  • Red: for yourself only.
  • Grey: Not supposed to be edited.

The tab "Values" contains the sandbox prefix in cell "A2". It should be emptied when dealing with a production environment.

Salesforce Users Import Template

The fields listed below are required and identified, in the "Users" tab, by a dark blue column header.

  • Alias
  • Email
  • EmailEncodingKey
  • LanguageLocaleKey
  • LastName
  • LocaleSidKey
  • CommunityNickname
  • ProfileId
  • TimeZoneSidKey
  • Username

👍 If you add new columns to the template use the field API Name as a column header so that you will be able to do an "auto-map" when configuring the data loader insert job.

Input - Users To create the CSV file for "Users" records, select the "Input - Users" tab, then menu "File", "Download as" and "Comma-separated values (.csv, current sheet)".

Then load in the "User" object with your preferred data loader.

Retrieving The User IDs

To retrieve the user IDs, simply copy the ID column from the "Users" insert success file into column "E" of the "Users" tab. The rows are kept in the same order to allow a simple "Copy & Paste".

Loading The Assignments

Assignments ("Permission Sets") and memberships ("Public Groups" and "Queues") are junction objects supporting no extra attribute. So, a pair of IDs is always the only thing to load.

Input - PS To create the CSV file for "Permission Sets" assignments, select the "Input - PS" tab, then menu "File", "Download as" and "Comma-separated values (.csv, current sheet)".

Then load in the "PermissionSetAssignment" object with your preferred data loader.

Input - Groups To create the CSV file for "Public Groups" memberships, select the "Input - Groups" tab, then menu "File", "Download as" and "Comma-separated values (.csv, current sheet)".

Then load in the "GroupMember" object with your preferred data loader.

Input - Queues To create the CSV file for "Queues" memberships, select the "Input - Queues" tab, then menu "File", "Download as" and "Comma-separated values (.csv, current sheet)".

Then load in the "GroupMember" object with your preferred data loader.

The End...

Related Posts & Resources

I hope you enjoyed this post. Don't hesitate to ping me on Twitter if you have any comment or question.

Fab 🐸