Prime Mover User Migration Documentation

Scope: Prime Mover Free / Pro version

Background

User migration support is added starting Prime Mover 1.1.0. If you created packages with older version, it does not include user migration and users will not be migrated to the new site or have the post authors correctly updated.

Always update to Prime Mover version 1.1.0 to start using this feature. And then re-generate export to avail this feature. This will include users in your backup/migration packages automatically.

Disabling or Enabling this Feature

User migration support is enabled by default in both free and pro versions of Prime Mover. However in 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 already same set of users (same user IDs from source site to target site). It would just be a waste of resources to include users in the migration (especially if you have tons of users).

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

If you like to exclude users in the migration, simply uncheck the box “Export users”.

There is also a constant that can 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 both free and pro versions of Prime Mover. When this constant is defined and set, it will not export users just like in the old versions of Prime Mover.

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

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

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

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

Prime Mover user migration export users this way:

• Retrieve your site users only. In a single site, this is straight forward. In a multisite, Prime Mover only retrieve users of the subsite being exported. Please review the site users in your users back-end to make sure they are correct and up-to-date users in your site/sub-site. These are the users that will be retrieved by Prime Mover.
• Prime Mover dump the users details and user meta detailed data to a json file (instead of a SQL file).
• In case of a site with large user base, Prime Mover breaks down the export into chunks.

How Prime Mover migrate or import users?

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

• It checks if the users json file exists in the package. If it exists, it will do user import. Otherwise if these json does not exist (such as the case with older version packages or you choose to exclude users), it will skip the user import step.
• It will read the json file by chunks and then import users by batches to the database.
• Once a user is imported, user meta, roles and its site assignment as also automatically imported.
• In a multisite, the user is only added as the user of the multisite subsite being imported. It will not add that user to any sub-sites.
• The user roles are also imported, so if a user has administrator role in the source site. The user imported should also have administrator role. Or if the user is editor, the user is also editor after migration.
• Prime Mover does not export or import users and assigned with 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 handles existing and new users?

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

• It checks user uniqueness by user email only. As no two or more distinct persons will normally share the same email address. (privacy reasons, personal security,etc.)
• It does not check user uniqueness by username as its possible that two or more distinct persons might have the same usernames (from different sites). The same case with user ID, display name, etc.
• A user is considered to exist in a target site if his/her email address exists on both source and target site.
• Otherwise if the user to be migrated has email address that is not yet added on the target site, this user is considered new (does not exist yet.).
• If the user already exist and is the one doing the migration (e.g. administrator of a certain single-site or network administrator in a specific multisite), the user login details are not updated (no password change, no username change). However the the display name, and user meta will be updated to fit the current site details being imported.
• If the user already exist and 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 its username (if its unique, otherwise WordPress will increment its username by appending a number to it)., display name , user meta ,etc. The goal is to copy user details as exact as possible from the source site to the target site since this is a migration.
• If the user does not yet exist on the target site, the user is inserted to the database with the same user login details, meta, etc. as the source site.
• Bear in mind that during this user migration, user details remain intact as it was in the source site. The one exception is user ID, for which WordPress generates a new user ID for new users added in the site. The user ID being generated for this new site may not be the same as the user ID of a specific user in the source site.
• The other rare exception is the username. When the user is inserted to 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 affects post and content authors?

Since users are migrated, the associated post and content authors are migrated as well. Prime Mover does some adjustment to make sure the user IDs of the post authors are consistent with the correct authors from the source site.

For example, say a user with email “test@test.com” and author of a post “Hello World”. This user originally has a user ID of 7 at the source site. WordPress uses this user ID to pinpoint to the correct content author.

When this site is migrated to some other site (whether to another single-site or multisite), WordPress generates another user ID which 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 target site. Prime Mover automatically adjust this during the post author update process. It will change the user ID of 7 (which is only correct in the source site ) to user ID of 10 at target site. As as result, the post content author assignment is still correct after migration.

Does Prime Mover export and import user taxonomies?

Yes, if your site is using user taxonomy it will be able exported and imported automatically just like post taxonomies ,etc.

Does user details secure in the package?

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

If you think security is your concern, especially if you store this package to remote cloud and other places (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 will not be anymore plain text.

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

I have PRO version, any tips on excluding users for better performance?

If your source site and target site are mirrors, then you can easily exclude users from your export. For most cases, we always recommend to include users in your export whenever possible.

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

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

Under these conditions, you can safely exclude users in the export to get faster export and restoration performance. If users ID from source site to target site does not correspond to each other . Then it is usually safer to include users in the export package so Prime Mover can automatically adjust users 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 now include the logs as well as to reproduce the issue. Finally send this log to us for analysis. You should disable the user logging and remove the logs after this troubleshooting.