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”:
Click on it to launch the migation process:
Step 1 - Start
At the first step of the wizard, 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:
Step 2 - Connect
At the second step of the wizard, 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, define 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.
- Site path: The site path of your X-Cart 4 store.
Click Save and continue.
Step 3 - Check
At 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 at earlier.
Provided that the connection details have been specified correctly you should be able to see a summary of information that X-Cart 5 was able to obtain regarding the data that can be migrated from your X-Cart 4 store:
The “Images size” item shows the amount of space taken by the X-Cart 4 store images (in Mbytes). If you are going to migrate the images, be sure to check that you have a sufficient amount of disk space on your X-Cart 5 store hosting for them.
Click Continue to proceed.
Step 4 - Select
At the fourth step of the wizard, you will see a list of data types that can be migrated from your X-Cart 4 store to X-Cart 5 (“What to transfer”), with check boxes.
Use the check boxes to select the data types that you want to be migrated to X-Cart 5, then click Save and continue:
If you wish to just try the migration in demo mode this time, select the Demo migration option at the top of the page:
Click Save and continue.
More info on Demo migration is available in the section How XC4 to XC5 Migration wizard works: Demo migration of this manual.
Step 5 - Enable
At the fifth step of the wizard, X-Cart will provide you with a list of X-Cart 5 modules that should be enabled if the wizard detects that your X-Cart 4 installation has features that are lacking in the default X-Cart 5 distribution pack but can be added by enabling certain X-Cart 5 modules:
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 you will get a license warning with a list of affected modules after the store has been deployed:
In this case, you have two options available:
- 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.
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:
On a LICENSED installation, the scenario of the wizard “Step 5 - Enable” will be a bit different after the Enable and continue button has been clicked.
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 as follows:
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.
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.
Step 6 - Transfer
At the sixth step of the wizard, 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 hence the migration wizard has collected all the information it requires and is ready to start the data migration process:
If orders are going to be migrated, you will get an alert message regarding the currency being used: “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 your X-Cart 5 store is using the same currency as was used in the X-Cart 4 store. Use the link in the alert message to quickly access your X-Cart 5 store’s currency settings (Store setup > Localization, Currency tab).
If you want to migrate not all your X-Cart 4 orders, but just the latest orders starting from a specific date, it is possible to specify the date using the Migrate orders from date field:
It is also possible to skip any X-Cart 4 store data that has already been migrated previously by enabling the Skip previously migrated data option:
More info on this option is available in the section How XC4 to XC5 Migration wizard works: Skipping previously migrated data of this manual.
To start the migration, click Start migration:
The migration process may take a while to complete and only continues while the page is open. Hence 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:
Migrating data… Moving the selected types of data from X-Cart 4 to X-Cart 5.
Processing products… Updating product related quick data and other types of data related to products, like calculating the bestsellers statistics based on the migrated orders.
Processing categories… Updating quick data for categories. Until this step has been completed properly, the category tree will not be displayed correctly.
Removing duplicate images… Removing any duplicate product images (if any product images got duplicated as a result of the migration).
The above stages will be included in any migration process - regardless of whether you are importing products/categories or not. If your X-Cart 5 store has products and categories, the processes run at these stages are simply necessary to ensure that your store looks and functions correctly.
The module “XC4 to XC5 Migration wizard” now does not do the resizing of images. The stage “Resizing images…” which used to be included in the migration process by earlier versions of the module has been excluded. Now if you need to resize the images before going into production with your X-Cart 5 store, you can do the resizing using the Generate resized images feature in the Look & Feel > Images section.
Step 7 - Complete
This is the final step of the wizard. Your data has been successfully migrated.
Please keep in mind that starting from X-Cart Classic v4.5.x user passwords are not stored in the database. Hence the passwords can’t be transferred savefy during the migration process and all users will have to use the Forgot password? option on the next login to the X-Cart 5 store in order to get in.
We’d recommend to add a special banner to the X-Cart 5 Sign in pop-up prompting the users to restore the password because of migration. A sample custom module that will add a label to the sign in form you can download here.
In some cases things may not go as smoothly as one would hope during the data migration procedure, e.g. 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).
If you wish to do another migration (for example, finish migrating your X-Cart 4 data after testing the migration in the Demo migration mode), you can restart the migration wizard using the Restart wizard button:
Help make this document better
This guide, as well as the rest of our docs, are open-source and available on GitHub.