This document is a work in progress!

Requirements for the CSV file

  • The CSV file needs to be a plain text file UTF-8 encoded.
  • The first line of the CSV file needs to hold the field names, or the fields to be imported needs to be in correct order (please see samples below)
  • Each row is in a new line
  • Each column is separated with a field delimiter character
  • At least the email address is provided.

The minimum of required CSV fields for importing users

To import users you need to provide a CSV file with at least 1 field: email - that's it!

"vader@imperium.com"
"jane.doe@mail.com"
"john.doe@mail.ru"
"sponge.bob@bottom.at"
"han.solo@rebels.org"

In this case the import engine automatically sets the email address as username (if you check the Set Email Adress as Username option, you can overrule eventually existing username values at any time).

Description of all supported import fields

Full row of user fields in correct order

email,username,password,fullname,phone,mobilephone,dob,gender,address,country,city,state,zip,fax,photo,comment,website,extended

Field properties

Field Requirements Note
email * max. 100 characters each valid email address
username max. 100 characters
password max. 255 characters If not provided, UserImport will create a randomized one
fullname max. 100 characters
phone max. 100 characters
mobilephone max. 100 characters
dob unix timestamp or a valid date format e.g 1966-10-05
gender single number 1 = male, 2 = female, 3 = other
address max. 65535 characters
country varchar 255
city max. 255 characters
state max. 25 characters
zip max. 25 characters
fax max. 100 characters
photo max. 255 characters
comment max. 65535 characters
website max. 255 characters
extended a valid Json formatted array There are two methods of importing extended fields (please see description below)!

User Import supports two ways of CSV file formatting:

  1. First line of CSV file contains field names (header row)
    This is the comfortable and recommended way!
  2. Without header row but fields in fixed order.

Method 1: Formatting the CSV file with first line containing field names

This is the recommended way of importing users!

Minimum required field: email. Furthermore you can provide as much fields as you need in any order you like. You don't need to fill the gaps of un-needed fields.

Sample

You want to import users with the following fields: email, username, fullname, firstname, lastname. (if you wonder about the last to fields, please keep on reading):

"email","username","fullname","firstname","lastname"
"vader@imperial.com","vader","Darth Vader","Darth","Vader"
"jane.doe@mail.com","janedoe","Jane Doe","Jane","Doe"
"john.doe@mail.ru","johndoe","John Doe","John","Doe"
"sponge.bob@bikinibottom.at","spongebob","Bob Sponge","Bob","Sponge"
"vaderjunior@imperial.com","vaderjunior","Darth Vader Jun.","Darth","Vader"
"han.solo@rebels.org","hansolo","Han Solo","Han","Solo"

You probably have already recognized the 2 fields firstname and lastname, which you know aren't valid user object fields.
And here comes the magic:
Each fields you provide, which aren't in the list of valid user object fields, are treated and saved as extended fields! Isn't this cool?

Method 2: Formatting the CSV file without header row but fields in fixed order

Minimum required field: email. Furthermore you can provide as much fields as you need. Un-needed fields between the first and the last used field needs to be provided as blank values.

Sample

You want to import users with the following fields: email, username, fullname, gender, address, country, city, state, zip, photo. One row of the CSV file would look like this (for better understanding we are using the field names as values):

"email","username","fullname",,,,"gender","address","country","city","state","zip",,"photo"

Full sample with extended fields

You want to import users with the following fields: email, username, fullname, gender, address, country, city, state, zip, photo, website, extended. The full CSV file would look like this (in the following sample we are using single quotes as field enclosure characters and semicolons as field delimiters because of Json formatted strings in last field):

'vader@imperial.com';'vader';'Darth Vader';;;;1;'Sector 1';'A Far Galaxy';'Deathstar';'Area 17';2233;;'pic1.jpg';;'http://darkside.vader.com';'{"firstname":"Darth","lastname":"Vader"}'
'jane.doe@mail.com';'janedoe';'Jane Doe';;;;2;;;;;;;'pic2.jpg';;;'{"firstname":"Jane","lastname":"Doe"}'
'john.doe@mail.ru';'johndoe';'John Doe';;;;1;;;;;;;'pic3.jpg';;;'{"firstname":"John","lastname":"Doe"}'
'sponge.bob@bikinibottom.at';'spongebob';'Bob Sponge';;;;1;'Bikini Bottom 37';;;;;;'pic4.jpg';;;'{"firstname":"Bob","lastname":"Sponge"}'
'vaderjunior@imperial.com';'vaderjunior';'Darth Vader Jun.';;;;1;'Sector 1';'A Far Galaxy';'Deathstar';'Area 18';2233;;'pic5.jpg';;;'{"firstname":"Darth","lastname":"Vader"}'
'han.solo@rebels.org';'hansolo';'Han Solo';;;;1;;;;;;;'pic6.jpg';;;'{"firstname":"Han","lastname":"Solo"}'

Extended fields in the above sample:
If you want to import extended fields without providing a header row in your CSV file, you need to provide this extra fields in form of a Json formatted string. Extended fields can also be nested. If you don't know what's a Json string, please have a look at the official json.org website!