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.

Supported file formats

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

JSON import

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

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. In this format, all fields are optional.

CSV import

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 be used for the current line.

Example:

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 consistent data is imported.

Profile import files must comply with the following requirements:

  • 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 optional salt and/or optional iterations)
  • SHA256 (with optional salt and/or optional iterations)
  • SHA512 (with optional postfix salt)
  • drupalSha512 (no optional salt and/or optional iterations as this information is contained within the hash)
  • sha256PostSalt (SHA-256 hash of password + salt, and optional iterations)
  • 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.