Users Import

User profiles can be imported using the administration console. This import allows to create new and ready-to-use users, or to update existing users.

The import is sequential, meaning that a single import file can have a profile creation followed by an update to the same profile.

File format

The profiles can be imported using either a JSON or a CSV file.

JSON file format

Each profile should be separated by a line feed character: \n.

For example:

{
  "external_id": "1",
  "email": "foo@gmail.com"
}
{
  "email": "bar@gmail.com",
  "name": "Joe",
  "gender": "M",
  "identities": [ { "provider": "facebook", "user_id": "123" } ]
}

The schema for the imported user is a regular user object as defined for the API. Every field of the format is optional and can be omitted.

CSV format

The CSV format uses a free format where columns are flattened JSON paths.

For example a path { "foo" : { "bar" : "test" } } will become foo.bar in the CSV header. If a column has no value, then the corresponding field will not used for the current line.

The same import as above would look like this in a CSV format:

external_id,email,name,gender,identities.0.provider,identities.0.user_id
1,foo@gmail.com,,,,,
,bar@gmail.com,Joe,M,facebook,123

Validation

Once parsed, every imported profile is then validated to ensure only coherent data is imported.

A few rules should be respected during profile import:

  • At least one unique field should be provided (several can be provided):

    • email (verified or unverified),
    • phone_number (if the SMS feature is available, verified or unverified),
    • a valid provider
  • At most a single matching profile should be returned for merging. The matching is made on:

    • uid (corresponding to the profile id),
    • email (verified or unverified),
    • phone_number (if the SMS feature is available, verified or unverified),
    • provider
  • Only one other profile can match the imported profile. If more than one user is matched, we can’t automatically define how to merge them, so an error will be returned.
  • Any provided consent should be defined for an existing key with a date anterior to the current date.
  • Any provided custom field should be defined for an existing key.
  • Any provided password hash should specify a valid hash method.

Import and merge logic

Security

Password hashes can be provided during the import under the password_hash field. Allowed algorithms are:

  • Bcrypt
  • MD5 (with optionnal salt and/or optionnal iterations)
  • SHA256 (with optionnal salt and/or optionnal iterations)
  • drupalSha512 (no optional salt and/or optional iterations because those informations are contained within the hash)
  • magentoSha256 (no optional salt and/or optional iterations)
  • Plain text

For example:

{
  "value": "..",
  "algorithm": "sha256",
  "salt": "...",
  "iterations": 1000
}
external_id,email,password_hash.value,password_hash.algorithm
46548,a1@a.aa,$S$5T/ViD4qlx6qHTQAci8eEbCuP/MVsoO8OSfU.xJsykqT5H6BXowl,drupalsha512

If a plain text password is used, the password will be hashed during the import using the bcrypt algorithm.

If a hashed password is used, the password will be hashed using the bcrypt algorithm only after the first login of the corresponding user.

Social login

Multiple social logins can be imported under the identities field. The provider name should be a valid provider name, and the user_id field should be the ID of the user on the provider’s website.

Merge

If a corresponding profile is found, then the profile will not be created but merged with the found profile. The matching is made on the following fields:

  • uid (corresponding to the profile id),
  • email (verified or unverified),
  • phone_number (if the SMS feature is available, verified or unverified),
  • provider

The priority of the merge is defined by the attribute updated_at. If the attribute is not present on both profiles, then the existing profile has priority over the imported profile.

The merge is a safe merge, meaning that (following the priority) no field will be overwritten. Fields can either be completed when they are lists or free objects (consents, custom_fields), created if empty, or ignored if already defined.

Limitations

There is no way to define to which provider an email or phone_number belongs to. Keep in mind that after the first login using a social provider, the profile’s information will be updated using the provider’s own information, completing the missing fields of the profile.