How to use data migration tool

My last post was about how to install and configure Magento 2 data migration tool. Now it is time to use it and to import data from your old shop. This post shows you a detailed introduction on how to set up data migration tool and use it. I also give you solutions for a number of problems you might get.

How to use data migration tool

There are 3 different things you can do with data migration tool:

• migrate configuration data
  
  php bin/magento migrate:settings /path/to/config.xml

  1	php bin/magento migrate:settings /path/to/config.xml

  
  With this command you migrate only configuration data from core_config_data database table. That is all you can find in system->configuration in your Magento 1 adminhtml.
• migrate data (products, customers, oders, …)
  
  php bin/magento migrate:data /path/to/config.xml

  1	php bin/magento migrate:data /path/to/config.xml

  
  This command is the main procedure of this data migration tool. It migrates all data (products, customers, orders, …) to your now Magento 2 and uses configurations done with mapping files.
• import deltas
  
  php bin/magento migrate:delta /path/to/config.xml

  1	php bin/magento migrate:delta /path/to/config.xml

  
  The main benefig of this tool is to import deltas, which means only changed data since last import. With this it is possible to create a Magento 2 shop parallel to your Magento 1 shop with same data basis. This minimize downtime if you switch to Magento 2.

The first step is now to copy configuration data.

Configuration data

My first try ended with an error message: Migration\Execution Invalid map file. I have not configured correct database connections and expected an error, but a different occured…

This message is a bit confusing. After some research, problem was that I deleted some files in config.xml from options tag. After copying from config.xml.dist I get the following more usable error: Access denied for user – one error message for each configured step in config.xml

Now configuration looks correct, so I set up correct connection data. The next run shows you the first error that has to do with data. If you have custom fields (not Magento default), then a message appears that you need to create mappings for this. It says: Source fields are not mapped.

If you do not want to do this, you can use param -a to ignore this differences and proceed. That may leads to another error.

Things become difficult now, because this is an SQL issue. You need to fix this in your database. The fix depends on type of error. An “Integrity constraint violation: 1062 Duplicate entry for key ‘STORE_GROUP_CODE’” can be easily fixed. Just make sure, that there are not 2 stores defined in core_store_group with the same name in your Magento 1 database.

Data

Now it is time to migrate all other data including products, orders and customers. On my first run I got errors so I need to adapt configuration in detail. Before this is possible, a deeper understanding of this process is necessary.

Magento 2 Documentation lists 4 steps that are done:

• Integrity check
  Each step has to check that the structure of data source (Magento 1 by default) and the structure of data destination (Magento 2) are compatible. If not – an error will be shown with entities that are not compatible. In case when fields have different datatypes (e.g. the same field has decimal datatype in Magento 1 and integer in Magento 2), a warning message will be shown (except when it was covered in Map file).
• Data Transfer
  In case integrity check passed, transferring data is running. If some error appears then rollback will run to revert to previous state of Magento 2. If a step class implements RollbackInterface then “rollback” method will be executed in case of error.
• Volume check
  After data has been migrated Volume Check provides additional check that all data was transferred correctly.
• Delta delivery
  Delta functionality is responsible for delivering the rest of data that was added after main migration.

At the end of computing your migration, you will get a red error box that tells you when this error occurred. If not, there is a good chance, that migration was successful.

Problems

If you work with data migration tool to get your Magento 1 data to Magento 2, you may have to handle a bunch of different errors first. It is not possible to list you all errors and possible solutions, but with an example I want to give you a starting point.

My first data migration run stopped with the following volume check failed error:

This happens in step 3 volume check and is a validation of already imported data. The log shows you, that the data migration tool does a rollback. A red list of error message shows all attributes that caused that problem. So what to do?

The answer is quite easy. All this attributes need a backend model, that is not present in Magento 2. You need a special mapping for this and this is done in class-map.xml. For each attribute you need to declare a new mapping. If you have no class already, yo can leave to tag empty. This is an example for the first attribute:

After declaring all renames, the migration runs to the next problem. This time there is a problem with database configuration:

This time we had to change max_allowed_packet param from you MySQL settings to more memory.

Revert everything

The data migration tool allows you to revert your recent migration if something brakes you database. Your first task after each try is to check, if frontend is accessible and if you can log into you adminhtml. If you get an error, you need to revert your changes, your database has an inconsistent status. Reverting is quite easy, simply use -r param like this:

Reverting is often usable, but sometimes it also crashes. If so, you need to import your last database backup.

Conclusion

Magento data migration tool is a very useful tool to migrate your shops data to the next level. It is quite cool to use, but it also has some problems. If you want to use it, be sure to invest some time to learn how it works, get an understanding of its steps and be prepared to solve some really strange problems.

I showed you how to solve two problems. Sometimes you need to do advanced configuration, sometimes you may also need to adapt database configuration.