Extend the tool
If the data format and structure created by Magento extensions or custom code is different between Magento 1 and Magento 2, use extension points in the Data Migration Tool to migrate the data. If the data format and structure are the same, the tool can automatically migrate the data without user intervention.
During migration, the Map Step scans and compares all Magento 1 and Magento 2 tables, including those created by extensions. If the tables do not differ, the tool automatically migrates the data. If the tables differ, the tool terminates and notifies the user.
Read the Technical Specification first before attempting to extend the Data Migration Tool. You should also review the Migration Guide for general information about using the tool.
Minor data format and structure changes
In most cases, the Map Step sufficiently resolves minor data format and structure changes using the following methods in the
- Change table or field names with mapping rules
- Transform data formats with existing handlers or create a custom handler
The following shows an example of using both mapping rules and a handler. This example uses a hypothetical Magento 1 extension called “GreatBlog” that has been improved for Magento 2.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 <source> <document_rules> <ignore> <document>great_blog_index</document> </ignore> <rename> <document>great_blog_publication</document> <to>great_blog_post</to> </rename> </document_rules> <field_rules> <move> <field>great_blog_publication.summary</field> <to>great_blog_post.title</to> </move> <ignore> <field>great_blog_publication.priority</field> </ignore> <transform> <field>great_blog_publication.body</field> <handler class="\Migration\Handler\GreatBlog\NewFormat"> <param name="switch" value="yes" /> </handler> </transform> </field_rules> </source> <destination> <document_rules> <ignore> <document>great_blog_rating</document> </ignore> </document_rules> <field_rules> <ignore> <field>great_blog_post.rating</field> </ignore> </field_rules> </destination>
Refer to the following for an explanation of the changes in the previous example:
- Unnecessary data from the index table
great_blog_indexshould not be migrated
- The table
great_blog_publicationwas renamed to
great_blog_postin Magento 2, so data should be migrated to the new table
summaryfield was renamed
title, so data should be migrated to the new field
priorityfield was removed and no longer exists in Magento 2
- The data in the
bodyfield has changed format and should be processed by the custom handler:
- A new ratings feature was developed for the “GreatBlog” extension in Magento 2
- A new
great_blog_ratingtable was created
- A new
great_blog_post.ratingfield was created
- A new
Extend mapping in other steps
Other steps support mapping, such as the EAV Step and Customer Attributes Step. These steps migrate a predefined list of Magento tables. For example, suppose that the “GreatBlog” extension has an additional field in the
eav_attribute table and the name changed in Magento 2. Since the table is processed by the EAV Step, mapping rules should be written for the
map-eav.xml file. The
map-eav.xml files use the same
map.xsd schema, so mapping rules remain the same.
Major data format and structure changes
In addition to the Map Step, there are other steps in the
config.xml file which migrate data with major format and structure changes, including:
- Url Rewrite Step
- OrderGrids Step
- EAV Step
Unlike the Map Step, these steps scan a predefined list of tables instead of all tables.
Create custom steps
Using the same “GreatBlog” example, suppose the extension contains three tables in Magento 1, but was redesigned to have only one table in Magento 2. To migrate all data from multiple tables to a single table, you can create a custom step in the
config.xml file. For example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 <steps mode="data"> ... <step title="GreatBlog Step"> <integrity>Migration\Step\GreatBlog\Integrity</integrity> <delta>Migration\Step\GreatBlog\Data</delta> <volume>Migration\Step\GreatBlog\Volume</volume> </step> </steps> <steps mode="delta"> ... <step title="GreatBlog Step"> <delta>Migration\Step\GreatBlog\Delta</delta> <volume>Migration\Step\GreatBlog\Volume</volume> </step> </steps>
The tool runs steps according to their position in the
config.xml file; from top to bottom. In our example, the
GreatBlog Step will run last.
Steps can include four types of classes:
- Integrity checking
- Data delivering
- Volume checking
- Delta delivering
Refer to Configuration, Step internals, Stages and Running modes for more information.
Complex SQL queries can be assembled inside these classes to fetch data from the three tables and migrate into a single table. Also, note that these tables should be “ignored” in the Map Step because it scans all existing tables and tries to migrate the data unless it is in the
<ignore> tag of the
Prohibited extension methods
Since the Data Migration Tool and Magento 2 are constantly evolving, existing steps and handlers are subject to change. We highly recommend not overriding the behavior of steps like the Map Step, URL Rewrite Step, and handlers by extending their classes.
Some steps do not support mapping and cannot be changed without altering the code. You can either write an extra step that changes data at the end of migration or create a GitHub issue and ask for a new extension point on the existing step.