Before installing the connector
You might be setting up an Akeneo PIM instance for the first time and you want to connect it to your existing Adobe Commerce.
Installing and configuring Akeneo Connector for Adobe Commerce is only a step of your migration process.
Indeed, in order to ensure that the data transfer and the connection between the two systems goes as smoothly as possible, there are a few steps you need take in account before configuring your connector.
Akeneo PIM catalog structure
You need to think about an Akeneo PIM catalog modelization that will correspond to your Adobe Commerce existing catalog structure. If the data structure you choose inside Akeneo PIM contrasts from your current setup in Adobe Commerce, you might be facing issues during data transfers and incompatibilities due to the many differences between your two systems.
On the other hand, setting up an Akeneo PIM instance for your business can also be the right time to review some of your catalog structure or your enrichment workflow.
You have to be aware that those structural changes might impact your existing Adobe Commerce catalog structure, and also the synchronizations with the connector.
In this case, some cleaning or restructuring inside Adobe Commerce might be needed before setting up the connector.
Initializing your catalog data from your Adobe Commerce or your ERP in your Akeneo PIM instance
After setting up your new Akeneo PIM instance, you will need to import your current catalog data, either from your existing Adobe Commerce or your ERP.
This process is specific, and will depend on your choices in terms of Akeneo PIM catalog structure and internal organization.
Akeneo Connector for Adobe Commerce is focused on synchronizing data from Akeneo to Adobe Commerce but it will never transfer data from Adobe Commerce to Akeneo PIM. This transfer has to be done independently.
Synchronizing your Akeneo PIM data to your Adobe Commerce for the first time
Once your Akeneo PIM instance is ready, the connector installed and configured on your Adobe Commerce, you can now proceed to your first synchronization between both systems.
Keep in mind that this kind of connection requires a lot of testing and data analysis afterward to make sure that there are no misconfigurations or undesired side effects.
A production environment should not be used to test the first synchronization between Akeneo PIM and Adobe Commerce.
We recommend you follow the guide below to check the integrity of your different Adobe Commerce entities, reconfigure it if necessary after the first import and also check the good behavior of your Adobe Commerce online store.
Installing Akeneo Connector for Adobe Commerce on an existing Adobe Commerce
As the catalog and entity structures between Akeneo PIM and Adobe Commerce are different, Akeneo Connector for Adobe Commerce uses a custom table (akeneo_connector_entities) to store the relations between Akeneo PIM entities and Adobe Commerce entities. Those relations are created once an entity has been imported with the connector.
Installing the Akeneo Connector for Adobe Commerce on an existing Adobe Commerce with existing entities like products or attributes that have not been imported with the connector means that the relations in Akeneo Connector custom table are not present yet, and that the Akeneo Connector doesn't know which Akeneo PIM entity is related to which Adobe Commerce entity.
Since the 100.3.4 version of the Akeneo Connector for Adobe Commerce, it is possible to automatically map some entity types from Akeneo PIM to existing entities in Adobe Commerce during the first import.
The supported types are Attributes, Options and Products. Below are the explanations for each entity and global recommendations to successfully connect your Akeneo PIM and your existing Adobe Commerce with the Akeneo Connector for Adobe Commerce.
Always make sure to backup your data and to test the synchronization on an existing Adobe Commerce in a non-production environment beforehand
Categories
At this point, it is not possible to automatically link Akeneo PIM categories and existing Adobe Commerce categories that have not been created with the connector.
This limitation comes from the fact that there is no category code inside Adobe Commerce that can be linked to the category code inside Akeneo PIM.
Our recommendation in this case is to import your category tree from Akeneo PIM with Akeneo Connector for Adobe Commerce, and use it to replace your existing Adobe Commerce tree, in your Adobe Commerce "Root category" store configuration when you are ready to move to the new structure.
When doing so, make sure that your products have been associated with your new category tree.
Families
At this point, it is not possible to link existing families from Adobe Commerce to Akeneo PIM families as there is no code inside Adobe Commerce to match with the Akeneo PIM family code.
Our recommendation is to import new families from Akeneo PIM, let the product job link your products to the new families, and delete the old families.
A family (attribute set) inside Adobe Commerce can be deleted only if no products are associated to it.
Attributes
When importing for the first time to an existing Adobe Commerce instance, attributes with the same code inside Akeneo PIM and Adobe Commerce will be automatically linked in the Akeneo Connector entity tables.
Make sure that the attribute type in Adobe Commerce matches your attribute type in Akeneo PIM.
If not, a warning message will appear and the attribute will be skipped.
Consult the Akeneo Connector default attribute type mapping for more information: Attribute types
Attribute options
When importing for the first time to an existing Adobe Commerce instance, attribute options are automatically linked to your existing Adobe Commerce attribute options based on their "Admin label".
If an option in Adobe Commerce for a specific attribute has an "Admin Label" matching the Akeneo PIM option label in your Adobe Commerce admin locale, the connector will setup the link during the first import.
Since the 101.6.0 version of the Akeneo Connector for Adobe Commerce, you can set Akeneo attribute option code as Admin label in Adobe Commerce. If you do so, the mapping will be based on the code of your attribute options in Akeneo corresponding to your existing Adobe Commerce attribute option Admin label. For more information, please consult the associated documentation: Configure Attribute Options
Since the version 103.3.0 of the Akeneo Connector for Adobe Commerce, if a select / multi-select / reference entity select / reference entity multi-select attribute is mapped from the "Attribute Mapping" configuration to an existing Adobe Commerce attribute with the same type, the options from the Akeneo attribute will automatically be created and mapped in the corresponding Adobe Commerce attribute.
To know more about the attribute type mapping from Akeneo to Adobe Commerce, please consult the Attribute type documentation page.
Product models and family variants
Product model and family variant jobs has been removed since the 101.0.0 version of the Akeneo Connector for Adobe Commerce and merged into the Product job
Product models and family variants data is stored into internal Akeneo Connector tables and will be used during the Product import job process.
This data doesn't need any link to Adobe Commerce entities so you will just have to launch the corresponding jobs to fetch the data from Akeneo PIM before launching the product job.
Products
Products are automatically linked from your existing Adobe Commerce product SKU and the Akeneo PIM product identifier. It includes simple and configurable products in Adobe Commerce (product models and variant products in Akeneo PIM).
The data coming from Akeneo PIM will replace the existing data inside your Adobe Commerce products.