Instead of importing your users from an external directory or entering users manually into OneLogin, you can import them in bulk by uploading a comma-separated values (CSV) file. You can also upload a CSV file to add and update attributes--including custom attributes--for existing OneLogin users. You can even use the CSV file to delete users.
Any user in your file whose email address isn't already included in the OneLogin cloud directory will be created as a new user. Any user in your file whose email address is already included in OneLogin will be updated with any new attribute values (or deleted if you choose).
Uploading a CSV file
- Log in to OneLogin as an admin and go to Users > All Users.
Go to the More Actions menu and select Import Users.
The Import users dialog will pop up.
(Optional) Click the Download CSV Template button to get a template that you can use to build your CSV file.
Create your CSV file.
Your file must include columns for
Important! You must enter these attribute names exactly as they appear in OneLogin.
Custom attribute columns must be labeled
custom_attribute_shortnamewhere shortname is the short name of the Custom User Field.
deletecolumn must be named as such and appear before the custom attribute columns. To delete a user, enter
deletecolumn. Any other value will be ignored, including a blank.
For attributes that can include multiple values per user (such as
role), separate those values using semicolons (
statusfield can be used to set the user's status at creation or change it for an existing user. You must use the numerical status value, which you can get here: https://developers.onelogin.com/api-docs/1/users/update-user
Tip. You don't need to set status=1 (Active) when you are creating new users, since they will be created as Active users by default.
groupfield behaves differently than other fields: if you enter a value of
none,the user will have no Group membership, and their Group membership value in OneLogin will display as "None." Conversely, if your user already exists, leaving the value blank does NOT remove any existing Group memberships; instead, no change is made. The
deletefields therefore differ from all other fields, for which a blank value in the CSV removes any existing attribute values for that field. (See the note below for more details)
If your CSV file includes users that already exist in the OneLogin cloud directory, the CSV import will update those users with any new attributes values that you included in the CSV, whether you added a new attribute column or updated attribute values in a column that was already included in a previous CSV upload.
Note. If you leave an attribute value blank, that attribute will have a blank value in OneLogin after you import the CSV. If you are updating an existing OneLogin user, and that user already has a value for that attribute in OneLogin, the CSV import will remove that attribute value and replace it with a blank value. The two exceptions to this rule are the
deletefields. See above for more information.
Upload the CSV file by clicking the Upload File button.
Monitor the progress of your import by going to Activity > Jobs.
The job is called CSV User Upload.
View the status of individual user creation or update events by going to Activity > Events.
In the following example, the import failed to create user Sally Wintergreen and succeeded in creating Bob Subramanian. In this example, you can also see that the Onboarding Task List has been enabled by the admin, and therefore Onboarding has been triggered for the new user.
Troubleshooting CSV user import
If your CSV file is formatted incorrectly or has any attribute names that don't exactly match the attribute name in OneLogin, the Import users dialog gives you an immediate error message when you click Import.
Typical issues are the use of
last_name instead of
lastname, as well as the failure to prefix custom attributes with
custom_attribute_ followed by the custom attribute's shortname (
If your CSV import succeeds but a particular user fails to be created or updated, you can go to Activity > Events and click the failed user to view details about the failure. In the screenshot from step 7, above, you can see that Sally Wintergreen could not be created. When you click the Sally Wintergreen row on the Events page, you see the following details dialog, which displays the reason for the failure:
In this example, you would need to double-check the name or formatting of the Group value included for Sally. In this case, there are two values for Group, and a user can only be a member of one OneLogin Group. You would revise the CSV file to include only one value for Group and re-upload the file.