CSV User Provisioning, Deprovisioning and Syncing Instructions

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/deprovisioning

Back to top

To set up CSV user provisioning:

  1. In Simpplr, go to Manage App > People > User Provisioning.
  2. Select Provisioning source > Simpplr User Services.
  3. Select Create new users if provisioning. 
  4. Select which fields you want to provision. First name, last name, profile, username, email, language, locale, and timezone are all required. 
  5. Select which manager unique identifier you want to use. Use the selection to populate the manager_unique_identifier column in the CSV.
  6. 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.
  7. 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. 
  8. 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. 
  9. Click Save.
  10. 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 (). 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.

mceclip0.png

select Simpplr User Services as provisioning source

mceclip1.png

if provisioning, select Create new users

mceclip2.png

select Manager's unique identifier

mceclip3.png

select Default details

mceclip4.png

choose whether to send password setup emails

mceclip7.png

if de-provisioning, select Deactivate users

 

mceclip0.png

setup email #1; a private key is attached to this email

mceclip1.png

setup email #2

 

Set up CSV user data syncing

Back to top

To set up CSV user data syncing:

  1. Go to Manage App > People > User Syncing.
  2. Select Syncing source > Simpplr User Services.
  3. Select which fields you want to sync.
  4. 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.
  5. 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.

  6. Click Save

  7. 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 (). 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.

mceclip9.png

select Simpplr User Services as syncing source

mceclip10.png

select unique ID

mceclip11.png

add custom field modal

mceclip12.png

select a custom field to sync

mceclip2.png

setup email #1; a private key is attached to this email

mceclip3.png

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.

Back to top

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 (country code required)
  • street
  • city
  • state
  • country
  • postal_code
  • language
  • locale
  • timezone

mceclip1.png

CSV provisioning template (not all columns shown)

  1. Name the CSV file you're provisioning from user-provisioning.csv.
  2. 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.
  3. 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.
  4. 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
  • email

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 (country code required)
  • street
  • city
  • state
  • country
  • postal_code

mceclip0.png

CSV syncing template (not all columns shown)

  1. Name the CSV file you're syncing from user-syncing.csv.
  2. 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
email
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 (country code required)
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

Back to top

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.

mceclip13.png

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:

      1. 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).
        Delete_subscriptions_1.gif
      2. Under Options for each subscription using an audience that contains custom fields, click the arrow icon, then Delete.
        Delete_subscriptions_2.gif
      3. 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. 
        Delte_audience_1.gif
      4. 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
        Remove_custom_fields_1.gif
      5. 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.
      6. 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.
        Change_syncing_source.gif

Links to templates

Back to top

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Comments

9 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)

    0
    Comment actions Permalink
  • 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. 

    0
    Comment actions Permalink
  • 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.

    0
    Comment actions Permalink
  • 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.

    0
    Comment actions Permalink
  • 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. 

    0
    Comment actions Permalink
  • 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!

    0
    Comment actions Permalink
  • Hi Kammie. No, that shouldn't impact any existing user data.

    0
    Comment actions Permalink
  • 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.

    0
    Comment actions Permalink
  • 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. 

    0
    Comment actions Permalink

Please sign in to leave a comment.

Articles in this section

See more