Bulk migration via CSV

Frontegg allows you to easily migrate users with a CSV file. The migration process imports users and their passwords, so once the migration is finalized, you can immediately switch from your legacy system to Frontegg, without needing to keep both platforms operating simultaneously.
You can now perform the migration process efficiently from your Users page located in your Management menu, where you must upload a JSON file describing the correlation between the column name of the legacy system and Frontegg.

Migration with multi-apps

Please note that automatic migration of users to different applications is not available. When migrating users, ensure that there is at least one default or auto-assigned application. If you need to segment user assignments across applications, you can assign users to their specific applications via this API after the migration.

Attribute mapping

To ensure a seamless transition between your legacy system and Frontegg, you must upload a JSON file formatted in key-value pairs where the key value will correlate with the values of your legacy system and the value field will correlate with those of Frontegg's. Note that the only mandatory fields for migrations are email and tenantId.

csv-migration

The following table lists all of the available Frontegg fields that can be included within your JSON file:

Frontegg Field	Format	Mandatory/Optional
`email`	string	Mandatory
`tenantId`	string	Mandatory
`name`	string	Optional
`profilePictureUrl`	string	Optional
`PasswordHash`	string	Optional
`authenticatorAppMfaSecret`	string	Optional
`phoneNumber`	string	Optional
`phoneNumberType`	string	Optional
`provider`	string	Optional
`metadata`	string	Optional
`vendorMetadata`	string	Optional
`verifyUser`	boolean	Optional
`roleIds`	string	Optional*

Migration with `roleIds`

To find the role ID, go to [ENVIRONMENT] → Entitlements → Roles, and click on More actions (three dots) icon next to the role. The 'Role ID' will be located under the Settings tab.

Roles must be created prior to migration.
If no roleIds field is specified during migration, the default role of the account will be applied.
You can state multiple IDs under the roleIds field in the following format (strings): {roleId}|{roleId}.

csv-migration

Importing passwords' hash

While not mandatory, if you opt to import users with their hash passwords, the format used should be supported by Frontegg. Choose the hash format from the dropdown menu in the second step of CSV migration (Select hash format) and follow the instructions to ensure proper migration.

Hashing Config

Note that if you use SCrypt or FirbaseScrypt as passwords hash, you must also provide a hashing config.

csv-migration

Importing phone numbers

If you're importing users with phone numbers for MFA or SMS login, select the authentication type for using the phone number during this step. Please note that SMS cannot be used simultaneously as both an MFA method and a login method. Once migrated, the user will be able to either login via SMS, or will promoted to MFA via SMS, depending on the chosen method.

csv-migration

Uploading your CSV file

After completing your attribute mapping and hash format selection, it's time to upload your CSV file and migrate your users to Frontegg.

CSV format

All CSV files should not have \n \r in their name format, otherwise the system will count the file as invalid. Make sure to run tr -d '\r' < filename.csv > filenameFixed.csv to ensure proper formatting.

csv-migration

CSV parameters and limitation

To ensure your CSV file is uploaded seamlessly, it must include the fields you uploaded previously in the attribute mapping file.

If a single file upload doesn’t suffice, you can upload multiple CSV files to support your user migration. into multiple files. You can upload up to 10 files of 1MB each. Each upload must contain a 'csv' suffix in its name.

Header row import

Whether you upload a single or multiple CSV files, the first file should include a header row specifying the attributes that must be imported. You must therefore specify from where Frontgg should extract the header to enact it on all subsequent files, like so:

csv-migration

User status after migration

csv-migration

Upon uploading your CSV file, the migration process will ensue. The users will be uploaded to your dashboard with the fields you indicated beforehand. Their status can be one of the following:

Active - user completed login after migration
Pending Login - user status after migration, before first login
Invited - user received an invite mail
Data error - fields were imported incorrectly

Possible errors in migration

A Data error status may occur if the CSV file columns do not correspond with the migrated fields correctly. If the Data error is for several users, you can manually adjust those users' metadata by choosing the Edit user & metadata option. If the Data error inflicts all users, you should check your attribute settings and re-import the file.

csv-migration