Science and Medicine Group

You can import a csv file with user data to the Survey Launcher.  You can both update existing users and add new users.  If you supply a user_id, that user will be updated.  If no user_id is provided, a new user will be added.

The easiest way to ensure that you are using the right csv format is to first export a file, then import.  This is especially important if you are updating existing users, as you may only want to update one or two fields and leave the rest the same.  If you want to add new users, you can simply add them to the end of the file and leave the user_id empty.

The Import Users function performs extensive validation of the data.  If any row fails validation, this is logged and the process continues.  At the end of the import, you will receive an email summarizing how many users were imported, how many were updated and a list of all errors that were encountered.  Validation errors slow down the import process considerably, so try to be sure that your data is clean to avoid lengthy imports.  Clean data should take about 1 second per user to import.  Validation errors will increase that number.

IMPORTANT NOTES:  

1. The export file will include the same user more than once if the user belongs to more than one organization.  When importing, you should be sure that the user appears only once in the file or any changes to the first row will be overwritten by the second row.  Be sure to delete any duplicates if you are updating.
2. Excel can add non-printable characters to the beginning and end of files, which may cause the file to not import.  Be sure to start with an exported csv file and do not change the file type.
3. Excel will also change the format of date fields.  Date/time fields must be imported as one of the following formats.  Other formats will result in an error.
   1.  "%Y-%m-%d %H:%M:%S"
   2. "%Y-%m-%d %H:%M"
   3. "%Y-%m-%d"
   4. "%m-%d-%y %H:%M"
4. Performance, as stated above, is about 1 second per user imported for clean data.  This is for updated users; new users are substantially faster to import.  There is about 5 minutes of overhead for starting the container and connecting to the database.
5. You can speed up the import of new users drastically by supplying an organization_id instead of a master_id.  If you supply a master_id, that adds an extra lookup to each row to get the organization_id for that master_id.
6. If an error occurs when adding an organization for a newly imported user, the user will still be imported, they just won't be associated with that organization.

When adding a new user, you can specify either a master_id or an organization_id.  You cannot specify both or an error will be generated.  You cannot add, remove or update a user's organizations after the user has been added via import.  You need to use the Survey Launcher to do that.  That is because a user can belong to many organizations.

Role_type_id, panelist_type_id, panelist and user_status_id are required fields so setting them to blank/empty will result in the field being added or updated with a default value.

The following is a list of fields in the csv file, with a description of what they are and if and how they can be updated.  Note that you do not need to supply all the fields to import users.  For new users, only two columns are required:  emailaddress and role.  For updating a user, you must supply at least a user_id, an emailaddress and role.  Only the columns you supply will be updated, BUT if you supply a column, it will be updated or inserted for every row.  So you must supply a valid value for every row.

Administrators and Interviewers that have been imported will be able to login to the Survey Launcher once imported.  Respondents will not.  You must use the Survey Launcher to create an Auth0 account for the user for them to be able to login to the Survey Launcher.  See <TODO>.

After creating or updating your csv file, you can import it on the "Users" page.  The import button is next to the export button.  When you click it, you will be asked to select a file to import.  The import will then run in the cloud until completed, at which point you will receive an email with a summary of the import, including any errors that were encountered.  The larger the file, the longer this will take.

Fields