Importing users when the file contains both existing and new users

Overview

This configuration explains how to safely import users from a file containing both:

• Existing users already present on the platform

• New users that do not yet exist

The objective is to create missing users without unintentionally modifying existing user names.

This situation commonly occurs during user imports where the source file contains a mixed population of users.

Why a two-phase import is required

Default import behavior

During a user import, the email field is generally used as the matching identifier.

However, when the import file also contains a Name column, existing user names will be overwritten during the import process.

This can become problematic because:

• User names are editable values

• Names are not stable identifiers

• The values in the file may differ from the values already stored on the platform

As a result, a single import may unintentionally replace existing user names with undesired values.

Typical example

A source file may contain:

• Existing users already present on the platform

• Newly created users

• Different naming conventions between the file and the platform

Even when the email matches correctly, the imported name may differ from the existing one.

Without additional precautions, the import updates the name of existing users.

Recommended approach

Core principle

The recommended approach separates the import into two phases:

1. Create only the missing users

2. Populate names only for users whose name is empty

This ensures that:

• Existing users remain unchanged

• Missing users are properly created

• Only newly created users receive the imported names

Import phase 1: Create missing users only

Objective

The first import creates users that do not yet exist on the platform.

At this stage, names are intentionally not imported.

Configuration

Result

After phase 1:

• Missing users are created

• Existing users remain unchanged

• Newly created users have an empty name

Import phase 2: Populate names for newly created users

Objective

The second import populates names only for users whose name is currently empty.

Since users created during phase 1 were created without names, they are the only users matching this condition.

Configuration

Result

After phase 2:

• Newly created users receive their names

• Existing users are ignored

• Existing names remain unchanged

When a single import is sufficient

A single import can still be used when:

• The file only contains new users

or

• Updating names of existing users is acceptable

In all other situations, the two-phase approach is recommended.

Benefits

This approach provides several advantages:

• Prevents unintended updates on existing users

• Safely handles mixed user populations

• Creates missing users without impacting existing data

• Avoids issues caused by inconsistent naming conventions

• Keeps email as the unique matching identifier