Migration to Magento 2: Migrating the Site

In the previous article of this series, I gave an overview of the Magento migration process and discussed some of the pros and cons to consider while planning your migration. In this article, we’ll dig a little deeper into the dirty technical details of the actual migration process.

Upgrading the Migration Tool

As we have already installed the Magento migration tool using the instructions in the previous article, the next step is to configure it properly for successful migration. Before you move ahead with configuring the migration tool, you need to check that your migration tool version matches your Magento installation version, and if it doesn’t, you need to update the migration tool version.

If you are migrating to Magento version 2.0.0, you need to have Migration tool version 2.0.0, likewise if you have Magento version 2.0.2, you need migration tool version 2.0.2. If there is a version mismatch, the migration won’t be successful, as different Magento versions can have different database structures and need different mapping mechanisms.

To check the version of your new Magento installation, use the following command:

1	php <Magento root directory>/bin/magento --version

Now check the version of the Magento migration tool. To do that, go to your migration tool directory and open the composer.json file. The location of this file will be something like this:

Magento root directory/vendor/magento/data-migration-tool/composer.json

In this file, find the value of version, and that’s your Migration tool version. If the version of Magento and the migration tool matches, you are all set to proceed to the next step. However, if they don’t, you need to change the migration tool version to match the Magento version.

Before you proceed with version upgrade, do take a backup of the data-migration-tool directory, because the upgrade process will modify this folder’s content, and if something goes wrong, you might not be able to get back the original one if you don’t have a backup. Once the backup is done, simply go to your Magento root directory in your server, and enter the following command:

1	composer require magento/data-migration-tool:2.0.2

The last thing in the command is your Magento version. In this case it is 2.0.0. If yours is different, change it accordingly.

Now that we have ensured that we have matching versions of Magento and the migration tool, it’s time to configure the migration tool properly.

Configuring the Migration

To configure the Magento migration, you’ll need to create/update the configuration file and the mapping files. You can find these files in this folder location:

Magento2 root directory/vendor/magento/data-migration-tool/etc/ce-to-ce

In this article, I’m demonstrating the community edition to community edition migration, so the last folder in the above path is ce-to-ce, but if you are dealing with the enterprise edition, it’ll be ee instead of ce.

Creating a properly configured config.xml file is a must, before you initiate any migration. To create the config.xml file, log in to your Magento server, and move to this directory:

<Magento2 root directory>/vendor/magento/data-migration-tool/etc/<migration edition>/ce

Use this command to create the config file:

1	cp config.xml.dist config.xml

Now, once it is created, open it up in any text editor, and put in this sample code:

<source>
    <database host="127.0.0.1" name="magento1" user="root" password="abc"/>
</source>
<destination>
    <database host="127.0.0.1" name="magento2" user="root" password="abc"/>
</destination>
<options>
    <source_prefix>magento1</source_prefix>
    <crypt_key>Look at Magento 1 root directory/app/etc/local.xml</crypt_key>
</options>

Here the host, name and user fields of both source and destination databases are mandatory. Also, the crypt_key field is mandatory. The rest of the fields like database password and source_prefix are optional.

The crypt_key field should have the same key as can be found in the key tag of the local.xml file, found in this directory:

<Magento1 root directory>/app/etc/local.xml

Now that we have created the config.xml file, the next optional step is updating the mapping files. The migration tool uses mapping files to perform database mapping from Magento 1 to Magento 2. The mapping files contain information on changing the table and field names of database, which tables and fields can be ignored, and other information like that. You can find the mapping files in this directory:

<Magento2 root directory>/vendor/magento/data-migration-tool/etc

Go through these files, and if you need to update any of these, make a copy of the file you need to edit, and remove the .dist from the name. For instance, if you are using the map.xml.dist file, make a copy of this file with the name map.xml. Once you are done editing them, you need to update the config.xml file with the new file name in the optional node. If you added the map.xml file, the previously created config.xml file’s code will become like this:

<source>
    <database host="127.0.0.1" name="magento1" user="root" password="abc"/>
</source>
<destination>
    <database host="127.0.0.1" name="magento2" user="root" password="abc"/>
</destination>
<options>
    <source_prefix>magento1</source_prefix>
    <crypt_key>Look at Magento 1 root directory/app/etc/local.xml</crypt_key>
    <map_file>etc/ce-to-ce/1.9.1.0/map.xml.dist</map_file>
</options>

Migrating Settings, Data, and Delta

Now that we are done with all the migration planning, installations, configurations and so on, let's actually start the migration process. For that, you’ll need to run the migration tool. To run the migration tool, enter your Magento server as a user with write permissions. To run Magento commands from any directory, add Magento Root Directory/bin to your system path, or you can run the commands this way:

1	cd <Magento root dir>/bin

Use the following command to start migration:

1	bin/magento migrate:<mode>{<path to config.xml>}

Here the mode can be either settings, data or delta, and the path to the config.xml file will be an absolute path.

You need to perform the migration in this order:

Migrate settings
Migrate data
Migrate delta (changes)

Migrating settings will migrate payment, tax, and shipping settings related to your stores, websites, etc. To run the settings migration, run this command:

1	bin/magento migrate:settings{<path to config.xml>}

This may not migrate all the data. You need to log in with the admin panel, to manually check if everything is transferred properly. If there is any problem, you can re-execute this statement, but this time, use the reset argument to start the migration from the beginning. The command will look like this:

1	bin/magento migrate:settings [-r\|--reset] {<path to config.xml>}

Once you are done with the settings, next start migrating data. The procedure is the same as before, with a single argument change. The command to be executed will look like this:

1	bin/magento migrate:data {<path to config.xml>}

When you run data migration, the migration tool checks that the database tables and fields of your old and newer Magento versions are consistent. In case of inconsistency it tries to find the information from the mapping files.

If it doesn’t find it there, it’ll throw an error mentioning troubling table and field names. The problem usually arises when you use a Magento extension whose table structure is not compliant with the Magento 2 database structure. In that case, you can either install the Magento 2 version of the extension or you can ignore those files by adding <ignore> tags to the map.xml file.

Once you solve the issue, you can re-run the migrate data command. One thing to keep in mind here is that the migration tool keeps track of the progress while migrating, and once you re-run it, it resumes from where it left before. To force it to start from the beginning, you can use the reset command like this:

1	bin/magento migrate:data [-r\|--reset] {<path to config.xml>}

The next step is to migrate the changes (delta).

As discussed in the previous article of this series, before beginning the migration process, you should stop the Magento 1 cron job and also all the activity in the Magento 1 admin panel other than necessary order management issues, and do not resume the activity till the time migration process is completed.

Although you'll stop most activity in the Magento 1 admin panel before starting the migration process, there will be some order processing issues going on. Also, maybe new user reviews or changes in customer profiles occur during this time. Now you need to migrate that data using incremental updates.

To migrate the incremental updates, run the following command:

1	bin/magento migrate:delta [-r\|--reset] {<path to config.xml>}

Here it is necessary to keep in mind that the incremental migration runs continuously unless you abort it using the CTRL + C command. Another thing to note here is that this tool only migrates data generated by Magento’s own modules. If a third-party extension generates/updates some data in the meantime, that will not be migrated. If you wish that data to be migrated as well, you’ll need to update the Magento 2 config files. That needs some advance knowledge of the data migration tool's internal specification, and it is beyond the scope of this article.

Manually Migrating the Data

Again referring back to the first article of this series, though the migration tool will do most of the heavy lifting of migration process, there are three types of files which you need to manually transfer:

Media Files
Store Front Design
ACLs (Access Control Lists)

To transfer the media files, first go to your Magento 1 admin panel. Go to System > Configuration > Advanced > System.

Under the Store Configuration for Media tab, Select the Media database from the list and click Synchronize.

Now go to the Magento 2 admin panel, Stores > Configuration > Advanced > System.

Under Storage Configuration for Media, select the media database, and click Synchronize.

This will take care of the media files which are stored in the Magento database. Now, to transfer other media files, copy the entire media folder from your Magento 1 root directory, and paste and merge it at this location in Magento 2:

Magento 2 root directory/pub/media

One very important thing to note here is that while copying you should not replace the .htaccess file. It is better to take a back-up copy of the .htaccess file before the media transfer, so that you don't accidentally replace the file.

To transfer the theme files of your store, you need to transfer the .phtml, js, css, and xml files to the appropriate locations in Magento 2. The folder structure is different than Magento 1. This article in the Magento dev docs will give you a good overview of the new theme folder structure of Magento 2.

Besides manually transferring theme files, you’ll also need to manually recreate credentials for the REST and SOAP web services you are using on your site, and also you’ll need to recreate administrative users and set their access privileges.

Post-Migration Steps

Now that you have completed all the steps required for Migration, here are a few last things to do to have a fully functional Magento 2 website.

You need to put Magento 1 in maintenance mode, and start a Magento 2 cron job.
Flush the Magento 2 caches, and re-index all indexes.
Change DNS to point to Magento 2, to divert traffic to the new site.

If you have made it thus far, congratulations! Your all new Magento 2 store is ready. The time and effort you put in to transfer the website to the newer Magento version will really be worth it. This new version of Magento offers enhanced performance and scalability, new features to boost conversion rates, and business agility and productivity improvements. Your site is ready to go to the next level with these enhanced features.