The upload wizard has three pages. On the first page you select the type of operation you want to perform - adding, modifying or deleting personal accounts.
On the second page you select the CSV file from your computer that you want to upload.
The final page after you click submit upload will either show details of where your file failed basic validation tests, or a message saying the file has been accepted and is being processed.
The basic validation looks first at whether any mandatory columns are missing and reports those before looking at anything else. If no mandatory columns are missing it looks at whether items are to long or short for that field, missing data, and items in the wrong format. A really cool feature here is that you can stay on that page, edit and resave your file to fix the identified problems, and then simply hit submit again to proceed.
The submitted for processing message does not necessarily mean that your upload is successful though, only that it passes the basic validation checks. There may still be errors that can only be discovered when the file is processed - e.g. trying to modify an account that does not exist, or create an account with a username that already does. If there are failures at this point then three things will happen:
- Any lines that have no errors are processed
- Any lines that have errors are reported:
- An email is sent listing the errors
- A message is available briefly in the interface that you can click on and view the errors
- Any lines that have errors are collected into a new file that is put in your downloads area for you to open, correct and re-upload.
Anything to watch out for?
To avoid problems with how different countries format dates, upload and download files always use yyyy-MM-dd. Some spreadsheet software will helpfully convert that to your local format when you open a data download file and if your spreadsheet program does this, you will have to manually change the date format for any date columns before saving and uploading the file.
If you're modifying accounts based on a data download, removing columns where there is no data being changed is a good idea for several reasons:
- It reduces the chance of you resetting any other changes made to the accounts between downloading the data and re-uploading it
- Fewer columns make it easier for you to check for and correct errors
- Fewer columns make it much easier for anyone else to check for and correct errors
- Uploads are processed slightly faster
- Errors are reported slightly sooner
Custom attributes added to your schema may or may not be mandatory and are not covered here, however the template you can download from the admin area will honour them and you will find they are the fields and behaviours you see on pages one and two of the create account wizard.
The standard fields that are always mandatory are:
If usernames are not specified, they will be generated by the system.
'status' is mandatory. If set to 'active' rather than 'pending' then the password field becomes mandatory too.
'emailAddress' is mandatory.
'forenames' and 'surname' are mandatory.
'emailUser?' is mandatory, but can be true or false.
Only 'username' is mandatory.
'permissionSets' when included as a column will remove permission sets from accounts if there is no data on that line so must be used with care.
If you specify a new organisation for an account (via 'adminUsername'), that organisation must be under your direct or indirect control or the account will not be moved. Also, when moving accounts, you cannot specify user groups or permission sets; you should instead include a 'useDefaultPermissionSets?' column and set it as true or false for each account you move. This column is on the upload template, but like 'emailUser?' is not included in a data download (because it is an operation rather than an account property).
If you are modifying email addresses, retain the 'allowEmailLogin' column (and data) setting true or false as appropriate to maintain that option.
Only 'username' is mandatory.