Using the module "XC4 to XC5 Migration wizard"
page last edited on 23 December 2016
Once the module “XC4 to XC5 Migration wizard” has been installed on your X-Cart 5 store, you get a new item at the top of the Admin area menu - “Migration wizard”:
To use the wizard:
Click on the “Migration wizard” item in the Admin area menu. The wizard will be launched.
At the first step of the wizard (“1. Start”), select the check box to confirm that you understand the consequences of using the wizard (namely, that any existing data in your X-Cart 5 store will be overwritten as a result of the migration process). Click Start migration to proceed:
As a result, the second step of the wizard will be loaded - “2. Connect”:
At the second step of the wizard (“2. Connect”), specify your X-Cart 4 store database connection details.
Start by completing the following fields:
- Database name: The name of your X-Cart 4 database.
- Database username: The username of your MySQL account.
- Database password: The password of your MySQL account.
If this set of fields is not enough to provide all the necessary connection details, please use the Advanced options section (expands at 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: The MySQL Unix socket.
- Table prefix: The table prefix used in your X-Cart 4 database (as was specified during X-Cart 4 installation). If you do not remember the table prefix that was used for your X-Cart 4 store, you can look it up in the file init.php of your X-Cart 4.x 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
After specifying the above details, provide the following settings:
- Encryption key: Your X-Cart 4 store Blowfish key (the secret key needed for access to certain types of data stored in X-Cart 4 in encrypted form, such as user passwords). For more info on X-Cart 4 Blowfish key, see X-Cart 4 manual.
- Site URL: The URL of your X-Cart 4 store.
Click Save and continue:
That will take you to the next step of the wizard - “3. Check”.
Using the connection details provided at the previous step, your X-Cart 5 store tries to connect to the specified X-Cart 4 database. Provided that the connection details have been specified correctly, at the third step of the wizard (“3. Check”) you should be able to see a summary of information that X-Cart 5 could obtain regarding your X-Cart 4 store:
Click Continue to proceed.
At the fourth step of the wizard (“4. Select”), you will see a list of data types that can be migrated from your X-Cart 4 store to X-Cart 5, with check boxes:
Use the check boxes to select the data types that you want to be moved to X-Cart 5, then click Save and continue:
If the module detects that your X-Cart 4 installation has features that are lacking in X-Cart 5 default distribution pack, but can be implemented by enabling certain X-Cart 5 add-on modules, at the next step of the wizard (“5. Enable”), it will provide you with a list of X-Cart 5 modules that you should enable so you can have the same features as in your X-Cart 4 store:
Click Enable and continue:
What happens next depends on whether your X-Cart 5 store is a trial installation or is using some kind of license (free or non-free).
On a trial installation, the module installer will activate all the required modules:
If any paid modules are installed and activated at this step, after the store has been deployed you will get a license warning like the following: with a list of affected modules.
In this case, you have two options available to you:
- Activate a license required to use the modules;
- Remove the modules from your store.
You may choose to resolve the licensing problem right away, or you may close the popup window with the warning and continue with the migration process. However, please be aware that the license warning will continue to appear in your X-Cart 5 store (both the store’s back end and the storefront) until you resolve the problem with your license or remove the modules.
If your X-Cart 5 store has some kind of license activated, after the Enable and continue button has been clicked, the scenario of the wizard step “5. Enable” will be a bit different. If, after downloading the modules recommended for activation in your X-Cart 5 store, the module installer detects that these modules may not be used with your type of X-Cart license, you will get a license warning like the following:
In this case, you will be able to resolve the problem using one of the following methods:
- Upgrade your X-Cart license to the license type allowed to use the modules;
- Remove the modules from your store.
Note that the modules will not be installed, and you will not be able to continue with the migration process until you resolve the problem with your license or remove the modules.
On our demo, we used a trial installation, so we got the first type of warning and chose to activate a license key for X-Cart Ultimate. After activating the key, we got a message at the top of the screen showing that the key has been activated successfully:
This means that our licensing problem has been resolved, and we need to go back to our migration wizard to continue with the migration process:
By the next step (“5. Transfer”), the wizard has collected all the information it requires and is ready to start the data migration process. You can see a list of X-Cart entities that will be transfered from your X-Cart 4 store to the X-Cart 5 platform:
Click Start migration.
The migration process begins:
Note that the migration process, which may take a while to complete, only continues while the page is open.
So be sure to keep the page open or, if you have to close it for a while, be sure to re-open it to allow the migration module to finish its work.
While your data is being migrated from your X-Cart 4 store to X-Cart 5, you will be able to see the progress on the screen. Here are the stages that will have to be completed:
Removing duplicate images:
Once the transfer has completed, the final step of the wizard will be displayed - “6. Complete”:
That is all; your data has been successfully migrated.
In some cases, during the migration of data, things may not go as smoothly as one would hope. For example, PHP execution may be interrupted. Problems like that tend to be related to the time limit settings of the web server, especially if working on a server with limited resources or on a slow internet connection. If you experience errors causing mid-process interruption of the migration, be sure to increase your server time limit (See Setting the time limit of your server) or decrease the migration_chunk_length value in etc/config.local.php (See How XC4 to XC5 Migration wizard works: Migration process).
Help make this document better
This guide, as well as the rest of our docs, are open-source and available on GitHub.