Once the X-Cart v4 to v5 Data Migration Wizard add-on has been installed, you will see a new Migration Wizard section at the top of the X-Cart 5 Admin area menu:
Click it to launch the migration process that consists of the following steps:
Step 1 - Start
In the first step of the wizard, select the checkbox to confirm that you understand the consequences of using the wizard. Namely, all the existing data in your X-Cart 5 store will be overwritten.
Click Start migration to proceed:
Step 2 - Connect
In the second step of the wizard, specify your X-Cart 4 store MySQL connection details.
Start by completing the following fields:
Database name: The name of your X-Cart 4 database.
Database username: The username of its MySQL account.
Database password: The password of its MySQL account.
If this set of fields is not enough to set up a proper connection, use the Advanced options section (expands by the click of the respective button):
In the Advanced options section, you can enter the following info:
Host name - the name of the host where your MySQL server is running;
Port number - the port number to use for the connection, for connections made using TCP/IP. The default port number is 3306;
Socket - Unix’ MySQL socket;
Table prefix - the table prefix used in your X-Cart 4 database (specified during X‑Cart 4 installation). If you do not remember the table prefix used for your X-Cart 4 tables, you can look it up in the file init.php of your X-Cart 4 installation (in X-Cart versions 4.5.3 and later, see the value of XC_TBL_PREFIX; in earlier versions - the value of xcart_tbl_prefix). The default table prefix for all X-Cart 4 versions is xcart_.
After specifying the above details, define the following settings:
Encryption key - the X-Cart 4 store’s Blowfish key (the secret key required to access certain types of data stored in encrypted forms, such as user passwords).
Site URL - The URL of your X-Cart 4 store;
Site path - this option represents where X-Cart 4 store is located on the server. Use it only when you have X-Cart 5 and X-Cart 4 on the same server.
Click Save and continue.
Step 3 - Check
In the third step of the wizard, your X-Cart 5 store tries to connect to the specified X-Cart 4 database using the connection details provided earlier.
If connection details are specified correctly, you will see a summary of information that is going to be migrated from X-Cart 4 to X-Cart 5:
The "Images size" item shows the amount of space taken by the X-Cart 4 store images in MB. If you migrate images, ensure that you have enough disk space on your X-Cart 5 hosting.
Click Continue to proceed.
Step 4 - Select
In the fourth step of the wizard, you will see a list of data types that the wizard can migrate from your X-Cart 4 store to X-Cart 5.
Select the data types that need to be migrated to X-Cart 5, then click Save and continue:
If you want to try to do the migration in the demo mode this time, select the Demo migration option at the top of the page:
Click Save and continue.
Step 5 - Enable
In the fifth step, the wizard will provide you with a list of X-Cart 5 add-ons that have to be enabled to match X-Cart 4 functionality:
Click Enable and continue.
The wizard "Step 5 - Enable" scenario can also be as follows. If the wizard detects that it is not allowed to use the add-ons with your type of X-Cart license after they are downloaded, you will get a license warning as follows:
In this case, you can resolve the problem either by upgrading your X-Cart license or by removing these add-ons.
The add-ons will not be installed, and you will not be able to proceed with the migration process until you upgrade the license or remove the add-ons.
Step 6 - Transfer
The next step will show you a list of X-Cart entities that will be transferred from your X-Cart 4 to X-Cart 5 because the migration wizard has collected all the needed information about them:
If orders are going to be migrated, you will get a warning message about the currency of these orders: "The orders will be migrated using the current store currency (Currency symbol - Currency name). You can change the currency here."
You need to make sure that your X-Cart 5 uses the same currency as X-Cart 4. Use the link in the warning message to quickly access X-Cart 5 currency settings (Store Setup > Localization > Currency tab) to double-check the current currency.
If you want to migrate X-Cart 4 orders starting from a particular date, it is possible to specify that date using the "Migrate orders from date" field:
It is possible to skip X-Cart 4's data that has already been migrated previously by ticking on the "Skip previously migrated data" option:
More info about this option is in Final Data Synchronization.
Click the Start migration button to start the process:
The migration process may take a while to complete, and it can only be running while the page is open. Hence make sure to keep the page open, or if you have to close it for a while, do not forget to re-open it to continue with the process.
While your data is being migrated, you can see the progress on the screen. Here are the stages that have to be completed:
Migrating data: Transitioning the data from X-Cart 4 to X-Cart 5.
Processing products…: Calculating product-related data, like bestsellers statistics based on the migrated orders.
Processing categories…: Calculating category-related data. The category tree will not be displayed correctly before this step is completed.
Removing duplicate images…: Removing any identical product images in case they got duplicated during the migration.
The stages above will be completed in any migration process, regardless of whether you import products/categories. If your X-Cart 5 store has products and categories, these processes are necessary to ensure that your store will look and function correctly.
Migration Wizard does not resize images because you may want to install another template with different image sizes so that this process can be run in vain. Once you decide what template to use, do the resizing manually using the "Generate resized images" button in the Look & Feel > Images section.
Step 7 - Complete
It is the final step when your data has been successfully migrated.
Please keep in mind that user passwords are not stored in the database. Hence the wizard cannot transfer the passwords safely during the migration process, and all the users will have to reset their passwords using the "Forgot password?" option on their next login to the X-Cart 5 store.
We recommend adding a special banner to the X-Cart 5 Sign-in popup prompting the users to restore their password after the store migration. A sample custom add-on for X-Cart 5.3.x that will add a label to the sign-in form can be downloaded here.
In some cases, things may not go as smoothly as one would hope during the data migration process. If you experience problems like the process freezing in the middle of migration, increase your server time limit or decrease the migration_chunk_length setting in the etc/config.local.php file.
If you want to do another migration (e.g., to finish the migration after testing it in the Demo mode), you can restart the migration wizard using the Restart wizard button:
Related pages: