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:

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:

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:

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

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:

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:

Use the following command to start migration:

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:

  1. Migrate settings
  2. Migrate data
  3. 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:

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:

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:

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:

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

As discussed in the previous
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

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
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:

  1. Media Files
  2. Store Front Design
  3. 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.

Selecting Media Database to 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

  • 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.