Prime Mover User Migration Documentation

Scope: Prime Mover Free / Pro version

Background

User migration support has been added, starting with Prime Mover 1.1.0. If you create packages with older versions, they do not include user migration, and users will not be migrated to the new site or have their post authors correctly updated.

To use this feature, constantly update to Prime Mover version 1.1.0. Then, re-generate the export to make it available. This will automatically include users in your backup/migration packages.

Disabling or Enabling this Feature

User migration support is enabled by default in both free and pro versions of Prime Mover. However, in the pro version, you can choose not to include users in the migration for a specific single site or subsite (in multisite).

This is helpful if you are migrating to a mirror site with the same set of users (duplicate user IDs from the source site to the target site). Including users in the migration would be a waste of resources (especially if you have many users).

This is how it looks like in the export options menu (for Pro version users):

To exclude users in the migration, uncheck the box “Export users.”

A constant can also be added to wp-config.php that globally disables user export. This is the constant:

define('PRIME_MOVER_DONT_EXPORT_USER', true);

This constant is usable for Prime Mover’s free and pro versions. However, unlike the old versions, it will not export users when defined and set.

If you have a Pro version and this constant set, the export user checkbox is not shown and is not usable in this case.

Is Prime Mover user migration data included in the exported database?

No, it’s because Prime Mover is also designed to migrate to a multisite subsite or from a multisite subsite to a single site database (and vice versa).

It does not dump the entire wp_users and wp_usermeta to a database table. If this is the case, it will dump the entire user’s table in a multisite (which is only one) that contains millions of users that do not have any relationship to your site’s actual users!

Prime Mover user migration export users this way:

• Retrieve your site users only. In a single site, this is straightforward. In a multisite, Prime Mover only retrieves users of the subsite being exported. Please review the site users in your user’s back-end to ensure they are correct and up-to-date users in your site/sub-site. These are the users that Prime Mover will retrieve.
• Prime Mover dumps the user’s details and user-detailed data to a JSON file (instead of an SQL file).
• Prime Mover breaks down the export into chunks for a site with a large user base.

How does Prime Mover migrate or import users?

In general (applicable to both single-site and multisite), Prime Mover imports users this way:

• It checks if the user’s JSON file exists in the package. If it does, it will import users. Otherwise, if this JSON does not exist (such as with older version packages or if you choose to exclude users), it will skip the user import step.
• It will read the JSON file in chunks and then import users by batches to the database.
• Once a user is imported, meta, roles, and site assignments are automatically imported.
• In a multisite, the user is only added as the user of the multisite subsite being imported; it does not add that user to any other subsites.
• User roles are also imported, so if a user has an administrator role in the source site, the user imported should also have an administrator role. Similarly, if the user is an editor, the user should also be an editor after migration.
• Prime Mover does not export or import users and is assigned super admin roles (in case of multisite) as this is on a network level (not sub-site level). The highest role imported is only an administrator for a specific site or sub-site.

How does Prime Mover handle existing and new users?

The following are rules on how Prime Mover handles existing users during the import stage:

• It only checks user uniqueness by email, as no two or more distinct persons will generally share the same email address. (privacy reasons, personal security, etc.)
• It does not check user uniqueness by username, as two or more distinct persons might have the same username (from different sites). The same is true for user ID, display name, etc.
• A user is considered to exist on a target site if their email address is present on both the source and target sites.
• Otherwise, if the user to be migrated has an email address that has not yet been added to the target site, this user is considered new (does not exist yet).
• Suppose the user exists and is migrating (e.g., administrator of a particular single site or network administrator in a specific multisite). In that case, the user login details are not updated (no password change, no username change). However, the display name and user metadata will be updated to match the imported site details.
• If the user already exists and is not doing the migration, the user login details will be updated to use the source site login details. The password of this existing user at the target site will updated to be the same as the source site. This includes its username (if it is unique; otherwise, WordPress will increment its username by appending a number), display name, user meta, etc. Since this is a migration, the goal is to copy user details from the source site to the target site as precisely as possible.
• If the user does not yet exist on the target site, the user is inserted into the database with the exact user login details, meta, etc., as the source site.
• Remember that during this user migration, user details remain intact as in the source site. Before Prime Mover 2.0.3 – the one exception was the user ID, for which WordPress generates a new user ID for new users added to the site. The user ID generated for this new site may not be the same as that of a specific user in the source site. Starting Prime Mover 2.0.3 and beyond, the source site user IDs are preserved after backup restoration and migration, but only if the user ID is not used in the target site database and the site is not multisite.
• The other rare exception is the username. When the user is inserted into the target site, but the source site username already exists on the target site (by a different user), WordPress will append a number to the username to make it unique before it is inserted. For example, if the username from the source is testone, it will become testone-1 at the target site (if there is already a user with the same username, testone).

How does user migration affect posts and content authors?

Since users are migrated, the associated posts and content authors are also migrated. Prime Mover makes some adjustments to ensure the user IDs of the post authors are consistent with the correct authors from the source site.

For example, consider a user with the email “test@test.com” who wrote the post “Hello World.” This user initially had a user ID of 7 at the source site. WordPress uses this user ID to pinpoint the correct content author.

When this site is migrated to another site (whether to another single site or multisite), WordPress generates another user ID that may not be the same as the source site (during user migration).

For example, the new user ID of “test@test.com” is now 10 at the target site. Prime Mover automatically adjusts this during the post-author update process. It will change the user ID of 7 (which is only correct on the source site ) to 10 at the target site. As a result, the post content author assignment is still accurate after migration.

Does Prime Mover export and import user taxonomies?

If your site uses user taxonomy, it will be exported and imported automatically, just like post-taxonomies, etc.

Are user details secure in the package?

User details are written to JSON files in plain text, just like what you can get with a native MySQL dump of other migration plugins (in .sql format); the data is not in any way encrypted.

If security is a concern, especially if you store this package in a remote cloud or other places (such as a flash drive, which others might read), you should encrypt user data. Prime Mover Pro supports this encryption feature. If you encrypt the package, the user details are automatically encrypted and no longer plain text.

Try the Prime Mover Pro 14-day trial to see how this user data encryption works.

I have the PRO version. Do you have any tips on excluding users for better performance?

If your source and target sites are mirrors, you can easily exclude users from your export. However, we recommend including users in your export whenever possible.

Mirror sites have the same set of users from the source and target sites. The same set of users means users have the same user IDs from both sites (corresponding to the correct users).

For example, if you have source site A with the following users:

Under these conditions, you can safely exclude users from the export to get faster export and restoration performance if the user IDs from the source site to the target site do not correspond. Including users in the export package is usually safer, so Prime Mover can automatically adjust user and author assignments.

How to enable user export and import debugging?

For privacy reasons, user import and export logging are not included in the default migration log that is found in /wp-content/uploads/prime-mover-export-files/

If you have issues with users’ export and import and would like to report this issue to us, please enable user logging first by adding this constant in wp-config.php:

define('PRIME_MOVER_LOG_USER_IMPORT', true);

Then, repeat the import/export process to include the logs and reproduce the issue. Finally, send this log to us for analysis. After this troubleshooting, you should turn off user logging and remove the logs.

Last updated: January 6, 2025