The following topics will be covered:

  1. Upload users in bulk
  2. Understanding the data file format



Upload users in bulk


In many cases, one would need to setup and manage a large number of users. You can use the 'Upload in bulk' feature (a tab under Setup → Users) to add, update or edit users in bulk by entering user metadata in an Excel spreadsheet, exporting it as a CSV (Comma-Separated Values) file, and uploading it in the web application.



Understanding the data file format


To understand how to enter the user metadata, do the following:

  1. Click on Setup → Users → Upload in bulk (tab).
  2. Download the CSV data file format by clicking "Download data file format for Users" (available on the right side of this page).
  3. Open this file in an Excel spreadsheet or any other text file viewer. A few points to note about rows or columns (fields) in this file:
    1. The first row is a header that provides the names of the various fields along with an instruction on the format of entry where it exists.
    2. The first column or field is always the type of operation you wish to perform: 'a' for add, 'e' for edit/update, and 'd' for delete.
    3. Mandatory fields are marked with a *.
    4. All fields expected here in a given row are the same fields as in the web form, and follow similar conventions for their values.
    5. An initial password can be specified for the users to get them started, but it is a best practice to ensure that the users change their password through the web or mobile application.
    6. Review the "Tips for filling user data" (available on the left side of the page) to be familiar with the password or other data entry guidelines (say, usage of commas within values).
    7. The user's preferred timezone value has to picked from the file that provides a list of recognised timezone values, which you can download by clicking "Download timezone codes" (available on the right side of the page).
  4. Once you have entered the data in a spreadsheet, save it and export or 'Save as' a CSV. You should now have a file with an extension .csv.
    1. NOTE: Mac computer users should ensure that they select "Windows Comma Separated (.csv)" when exporting the file for it to be recognised correctly by the application.
  5. Once you have the CSV file, click "Choose file", select the .csv file and upload it by clicking the "Upload" button.
  6. Once the file is successfully uploaded, the system processes the data in the background, one row at a time, creating the users in the system. The fully correct entries result in a successful operation (say, creation, edit or delete of user), while the rows with errors are rejected (i.e. there is no user created, edited or deleted). You can view the status of the upload and specific errors in the "status" panel at the top of this page.
  7. Review the status of the upload in the very first panel in the page (which shows the 'upload' icon).
    1. On the left, it indicates the name of the last file uploaded (which can be viewed by clicking it), the time of upload and the user who uploaded it. On the right, 
    2. On the right, it indicates the status of the upload, say, whether it is pending or done, along with the number of errors in the data uploaded. You can use the 'Refresh' icon beside the errors to get the most recent error status (since the errors accumulate over time as each user data is processed).
  8. If there were errors, then click on the 'n errors' link to see the list of errors. A panel expands to show errors by row, along with a character offset for that error (number of characters from the beginning of the file until that error), along with a description of the error by field in that row. The exact CSV fields for that user are also shown (in case you wish to identify this row by the user Id or other fields). The screenshot below shows a sample error panel with two errors in one row.
  9. You can now create a new CSV that only includes the corrected rows, and upload it again into the application to ensure successful operations.
    1. NOTE: Do not include the rows from the original CSV file that were already successful, since certain operations, such as add/delete, will fail if the user was existent/non-existent, resulting in more errors.


At this time, with no more errors showing in the status panel, your bulk upload of users is complete. You can go to the Users listing view to review that your users are indeed created in the system.