This article shows app managers how to provision, deprovision, and sync user data from their HRIS system using a CSV file. CSV templates for provisioning and syncing, with all the necessary columns, are attached to the bottom of this article. When provisioning or syncing in Simpplr, app managers will select which columns they want to map from the CSV, and ensure the columns they want to map contain the appropriate data.
- Set up CSV user provisioning/de-provisioning
- Set up CSV user data syncing
- Prepare your CSV file
- Error handling
- Reactivating deactivated users
- Switching from another syncing source to CSV/Simpplr User Services
- Links to templates
Set up CSV user provisioning/deprovisioning
To set up CSV user provisioning:
- In Simpplr, go to Manage App > People > User Provisioning.
- Select Provisioning source > Simpplr User Services.
- Select Create new users if provisioning.
- Select which fields you want to provision. First name, last name, profile, username, email, language, locale, and timezone are all required.
- Select which manager unique identifier you want to use. Use the selection to populate the manager_unique_identifier column in the CSV.
- Select the default language, locale, timezone, and profile for all users. If you'd like to have a different language, locale, timezone, or profile for a specific user, you can input that data in the corresponding column of the CSV.
- Choose whether to send password setup emails. Unless your organization uses SSO to login, you'll want to send password setup emails to users. Password setup emails will be sent from Salesforce, and will expire in 24 hours.
- Select Deactivate users if de-provisioning. Simpplr only needs a unique ID to de-provision users. Select which one you want to use, and populate the matching column in the CSV.
- Click Save.
- If this is the first time you're setting up CSV provisioning or syncing on your intranet, you'll receive two emails from your intranet titled Continue to set up user provisioning on <intranet name>. These emails will be from Simpplr User Services (user-services@simpplr.com). Use the information in these two emails to upload your CSV files to the dedicated SFTP location.
Caution
If you want to switch syncing sources from Simpplr User Services to another source after saving, wait five minutes before doing so. Otherwise, you won't be able to use the CSV file to provision, de-provision, or sync in the future.
select Simpplr User Services as provisioning source
if provisioning, select Create new users
select Manager's unique identifier
select Default details
choose whether to send password setup emails
if de-provisioning, select Deactivate users
setup email #1; a private key is attached to this email
setup email #2
Set up CSV user data syncing
To set up CSV user data syncing:
- Go to Manage App > People > User Syncing.
- Select Syncing source > Simpplr User Services.
- Select which fields you want to sync.
- Select which unique identifier you want to use. Use the selection to populate the unique_identifier and manager_unique_identifier columns in the CSV. Note, if the unique identifier you choose ever changes (e.g., a user's last name changes, so their email changes) you'll need to update that identifier in your CSV and reupload so the sync can capture the new unique identifier.
-
You can add a custom field by clicking add custom field and selecting a custom field option. Each custom field option has a corresponding column in the CSV. In the modal, click on the dropdown to select from custom field options 1 - 5. Input your data in the matching custom_field_X column of the CSV.
-
Click Save.
- If this is the first time you're setting up CSV provisioning or syncing on your intranet, you'll receive two emails from your intranet titled Continue to set up user syncing on <intranet name>. These emails will be from Simpplr User Services (user-services@simpplr.com). Use the information in these two emails to upload your CSV files to the dedicated SFTP location.
Caution
If you want to switch syncing sources from Simpplr User Services to another source after saving, wait five minutes before doing so. Otherwise, you won't be able to use the CSV file to provision, deprovision, or sync in the future.
select Simpplr User Services as syncing source
select unique ID
add custom field modal
select a custom field to sync
setup email #1; a private key is attached to this email
setup email #2
Prepare your CSV file
Note:
If you're using a CSV file to update any provisioning or syncing fields, please note that any fields included in the CSV file will reflect changes once uploaded back into Simpplr. So if the field is empty in the CSV file, it will be empty once uploaded back into Simpplr. This goes for fields that had previously contained information in Simpplr. So if you do not want to update a certain field, best practice is to leave it out of the CSV file. for more information on backing up Simpplr data, click this link.The CSV files for provisioning and syncing should contain a number of columns that can be mapped with Simpplr. During provisioning and syncing setup, app managers will select which columns they want to map (some columns are required).
Provisioning/Deprovisioning
You can download the CSV template for provisioning in the section below, which contains the following columns:
- is_to_be_provisioned (required)
- is_to_be_deprovisioned (required)
- first_name(required for provisioning)
- last_name(required for provisioning)
- about
- federation_identifier
- birthday (must be entered in yyyy-mm-dd format)
- job_title
- department
- division
- company
- hire_date
- manager_unique_identifier
- profile
- employee_number (required if selected for de-provisioning)
- username (required for provisioning; required if selected for de-provisioning)
- email (required for provisioning; required if selected for de-provisioning)
- phone
- phone_extension
- mobile_phone
- street
- city
- state
- country
- postal_code
- language
- locale
- timezone
CSV provisioning template (not all columns shown)
- Name the CSV file you're provisioning from user-provisioning.csv.
- In the CSV, make sure all users you want to provision have a 1 in the is_to_be_provisioned column, and a 0 in the is_to_be_deprovisioned column.
- Make sure all users you want to deprovision have a 0 in the is_to_be_provisioned column, and a 1 in the is_to_be_deprovisioned column.
- Populate the columns you want to map, following the field format requirements in the section below.
Syncing
You can download the CSV template for syncing in the section below. It will contain whichever of these three columns you selected as the unique identifier:
- employee_number
- username
This unique identifier field is only used for data mapping. Its data will not be synced. The CSV will also contain the following columns:
- first_name
- last_name
- about
- birthday
- job_title
- department
- division
- company
- hire_date
- manager_unique_identifier
- profile
- employee_number (required if selected)
- username (required if selected)
- email (required if selected)
- phone
- phone_extension
- mobile_phone
- street
- city
- state
- country
- postal_code
CSV syncing template (not all columns shown)
- Name the CSV file you're syncing from user-syncing.csv.
- Populate the columns you want to map, following the field format requirements in the section below.
CSV field format requirements
| Column | Required format |
| is_to_be_provisioned |
0 for no and 1 for yes
|
| is_to_be_deprovisioned |
0 for no and 1 for yes
|
| username |
string, max 80 characters, must be in the form of an email address (i.e. xxxx@xxx.com), but does not have to be a valid email address (https://help.salesforce.com/s/articleView?id=000325738&type=1)
|
| employee_number |
string, max 20 characters
|
|
string, max 128 characters
|
|
| first_name |
string, max 40 characters
|
| last_name |
string, max 40 characters
|
| job_title |
string, max 80 characters
|
| birthday |
in YYYY-MM-DD or MM-DD format (year is optional)
|
| hire_date |
in YYYY-MM-DD format
|
| about |
string, max 2000 characters, plain text, no HTML
|
| locale |
locale for the user from this list: https://help.salesforce.com/articleView?id=sf.admin_supported_locales.htm&type=5
|
| language |
language code for the user from this list: https://help.salesforce.com/articleView?id=sf.faq_getstart_what_languages_does.htm&type=5
|
| timezone |
one of the values from this list: https://help.salesforce.com/articleView?id=sf.admin_supported_timezone.htm&type=5
|
| profile | Profile id of the desired profile type in Salesforce: https://help.salesforce.com/s/articleView?id=000312782&type=1 |
| company |
string, max 255 characters
|
| division |
string, max 80 characters
|
| department |
string, max 80 characters
|
| manager_unique_identifier |
If provisioning: this column will be the identifier of the manager, where the type of identifier(username/email/employee_number) is based on the selection on the setup screen.
If syncing: this column will be the identifier of the manager, where the type of identifier(username/email/employee_number) is based on the selection for the user's unique identifier on the setup screen.
Same format requirement applies for each type of identifier.
|
| phone |
string, max 40 characters, in the format of "+1 917 555 8990"/ "+19175558990"
|
| phone_extension |
string, max 40 characters
|
| mobile_phone |
string, max 40 characters, in the format of "+1 917 555 8990"/ "+19175558990"
|
| street |
string, max 255 characters
|
| city |
string, max 40 characters
|
| state |
string, max 80 characters
|
| country |
string, max 80 characters
|
| postal_code |
string, max 20 characters
|
| custom_field_1 |
string, max 255 characters
|
| custom_field_2 |
string, max 255 characters
|
| Federation Identifier |
string, max 512 characters
|
| custom_field_3 |
string, max 255 characters
|
| custom_field_4 |
string, max 255 characters
|
|
custom_field_5 |
string, max 255 characters
|
CSVs should contain a number of columns that can be mapped with Simpplr. Templates of both can be found below in this article. DO NOT change the names of the files after you prepare them for upload.
Error handling
If there are any errors when provisioning, de-provisioning, or syncing, the App manager will receive an email with an attached error log. The error log will contain an error message and the row number in the CSV that contains the error.
error email
Error messages and explanations
| Task | Error message | Explanation | Solution |
|
Provisioning |
User provisioning not fully enabled: "Created new users" selected but value in "is_to_be_provisioned" is 0. |
This error happens when "Create new users" selection on the setup screen is enabled but the “is_to_be_provisioned" column in the CSV file is 0. |
Either disable the selection, or populate the column with 1. |
|
Provisioning |
User provisioning not fully enabled: "Don't create new users" selected but value in "is_to_be_provisioned" is 1. |
This error happens when "Create new users" selection on the setup screen is disabled but the “is_to_be_provisioned" column in the CSV file is 1. |
Either enable the selection, or populate the column with 0. |
|
Deprovisioning |
User deprovisioning not fully enabled: "Deactivate users" selected but value in "is_to_be_deprovisioned" is 0. |
This error happens when "Deactivate users" selection on the setup screen is enabled but the “is_to_be_deprovisioned" column in the CSV file is 0. To fix: either disable the selection, or populate the column with 1. |
Either disable the selection, or populate the column with 1. |
|
Deprovisioning |
User deprovisioning not fully enabled: "Don't deactivate users" selected but value in "is_to_be_deprovisioned" is 1. |
This error happens when "Deactivate users" selection on the setup screen is disabled but the “is_to_be_deprovisioned" column in the CSV file is 1. |
Either enable the selection, or populate the column with 0. |
|
Provisioning/Deprovisioning |
User provisioning and deprovisioning conflicting: value in “is_to_be_provisioned“ and “is_to_be_deprovisioned“ are both 0. |
When the “is_to_be_provisioned" and “is_to_be_deprovisioned" columns in the CSV file are both 0. |
If provisioning is intended, change the “is_to_be_provisioned" column to 1. If de-provisioning is intended, change the “is_to_be_deprovisioned" column to 1. |
| Provisioning/Deprovisioning |
User provisioning and deprovisioning conflicting: value in “is_to_be_provisioned“ and “is_to_be_deprovisioned“ are both 1.
|
When the “is_to_be_provisioned“ and “is_to_be_deprovisioned" columns in the CSV file are both 1. |
If provisioning is intended, change the “is_to_be_deprovisioned" column to 0. If de-provisioning is intended, change the “is_to_be_provisioned" column to 0.
|
|
Provisioning |
Username is not unique. Record skipped. |
The "username" column has value that is not unique. |
Check for other records with redundant value in the "username" column. |
|
Provisioning |
Manager's unique identifier is not unique. |
The "manager_unique_identifier" column has value that is not unique. |
Check for other records with redundant value in the "manager_unique_identifier" column. |
|
Provisioning/Deprovisioning/Syncing |
Mandatory field is empty: value in <column name> is empty. |
A mandatory field has empty value in <column name> in the CSV file. |
Fill in the <column name> with valid value. |
|
Provisioning/Deprovisioning/Syncing |
Field with wrong format: value in <column name> has wrong format. |
The format of <column name> in the CSV file does not meet the required format. |
Check and correct the format of the value of <column name>. |
|
Deprovisioning/Syncing |
Unique identifier is empty: value in <column name> is empty. |
The specified unique identifier field has empty value in the corresponding <column name> in the CSV file. |
Fill in the <column name> with valid value. |
|
Deprovisioning/Syncing |
Unique identifier is not unique. Record skipped. |
The specified unique identifier field has value that's not unique in the corresponding <column name> in the CSV file. |
Check for other records with redundant value in <column_name>. |
|
Provisioning |
New record created but encountered runtime error: <Runtime error message>. |
Simpplr encountered a runtime error that results in a new user being provisioned, but certain fields failed to sync value. |
Check for the <Runtime error message>. Contact Simpplr Support for any further questions. |
Reactivating deactivated users
There are a few ways to reactivate a deactivated user. This is a common use case for organizations who have seasonal employees who don't need to be on Simpplr full time.
Reactivating a single user
To reactivate an individual user profile, go to your Salesforce instance. In Setup, type Users into the Quick Find box and select. Find the name of the user in question and click. In their profile, check the box next to Active and click Save. That user is now reactivated in your Simpplr instance.
Reactivating users via CSV
Simpplr supports user reactivation through CSV with the same process as provisioning a new user. The CSV file used for reactivation is the same as provisioning.
- The old username, profile, and email must be provided in the CSV.
- Once the file is processed successfully, inactive users are moved to Active status.
- In case of any failure, the System admin will receive the error email with the failure reasons.
Note:
Reactivation only changes the user status from 'Inactive' to 'Active' while retaining user data. If any user data needs to be updated, it has to be synced.Switching from another syncing source to CSV/Simpplr User Services
Often customers will want to switch from their current user syncing source to a CSV file. While this is definitely possible, there are a few required steps before changing your syncing source.
First, you'll need to remove all subscriptions and audiences that are using custom fields. If you don't have any subscriptions or audiences using custom fields, move on to step 4 below.
Note:
We highly recommend copying or taking a screenshot of all your custom fields, audiences and subscriptions before deleting them so you'll remember them when setting up your new syncing source. To see your custom fields, go to Manage > Application > People > User syncing then scroll down until you see Sync additional fields.
To delete a subscription:
- Go to Manage > Subscriptions from your user menu. (Note, if you have Segments enabled, be sure to choose All segments from the dropdown once you reach this menu).
- Under Options for each subscription using an audience that contains custom fields, click the arrow icon, then Delete.
- Once all your applicable subscriptions have been deleted, perform the same action for audiences. Go to Manage > Audiences and under Options, click the arrow icon, then Delete. If you're not sure which audiences are using custom fields, Click Edit in the arrow icon to view all the audience's attributes.
- Now that your subscriptions and audiences have been removed, you must remove any custom syncing fields created. To begin, go to Manage > Application > People > User syncing
- Scroll down to the bottom where you see Sync additional fields and click the x icon next to each custom field. Then be sure to click Save.
- Scroll to the top of the page and choose a new syncing source from the dropdown list. In this case, we'll choose Simpplr User Services. Now you can follow the instructions above to complete your user syncing via CSV. You'll also be able to re-add your custom fields, as well as recreate your audiences and subscriptions once syncing is complete.
Comments
Hi, we have the following error under Manage > Application > People > User synching. Can you please add a troubleshooting info above for what might cause this?
Last sync on Oct 16, 2023 at 12:24am (failed)
Hi Natasha. If you're the App manager for your instance, you should've received an email indicating what caused the syncing scheduler to fail. Did you receive this?
Without seeing what's happening in the instance, I can't determine what the best troubleshooting steps would be to take here. I would recommend submitting a ticket with our Support team for this issue. They'll be able to access the environment and dig deeper into what could be causing the problem.
Hi Matt, I am System Admin and did not receive an email saying that the sync has failed. I have raised a ticket with support but thought you might know the answer. Thanks.
Hello! I have two questions and appreciate your help.
1. We can have SSO and CSV provisioning at the same time in the same instance as a hybrid approach and as needed, correct?
2. We have existing subscriptions using custom fields, e.g. Office Location. From the article it sounds like we will have to delete all those Office Location subscriptions before switching to CSV syncing. If this is the case, what suggestions do you have if we want to maintain those subscriptions? Thanks.
Hi Kammie.
1. Correct. A hybrid approach can work.
2. Unfortunately there's no way to hang on to the subscriptions using a custom field. The custom fields have to be removed in order for CSV syncing to work. Once the new syncing is done, you can re-add the same custom fields and subscriptions.
Hi Matthew, with a hybrid approach (AD + CSV provisioning), when we do syncing, for example: we use csv provisioning to provision 5 new users, and then change the AD sync to Simpplr Services/CSV sync. During the csv sync, will it impact the existing AD users? I would assume no, but just wanted to double check. Thanks!
Hi Kammie. No, that shouldn't impact any existing user data.
Hi Matthew, with a hybrid approach (AD + CSV provisioning), does it mean we can have a hybrid syncing approach as well? That we can switch AD sync and CSV syncing as needed without any issues nor impacting any existing user data? Thanks.
Hi Kammie. I can't say for certain whether or not this would impact existing user data if made a regular practice. It might be worth talking with your CSM or account rep to help them understand your use case and see if there's a less manual solution that could work for you.
Please sign in to leave a comment.