Select Page

Setting up the Akeneo Connector in Magento 2: Part 4 – Custom Product Data Mapping

June 18, 2021

If you’ve made it this far through the Magento 2 connector series you should already know how powerful the Akeneo Connector in Magento 2 can be when configured correctly. For this final installment I’ll be covering the Products menu found in the Magento Admin Panel at Stores > Settings > Configuration > Catalog > Akeneo Connector. If you are looking for information about setting up the connector, running the jobs, or filtering your import data see Part 1Part 2, and Part 3 of this series. Otherwise, let’s begin.

The Products menu is both the most powerful and most difficult to use tool within the Magento 2 connector. The main difficulty stems from the lack of feedback you receive from the system when one of the fields isn’t configured correctly. This article will help you understand exactly how each of these fields is used so you can get the configuration correct without any headaches. Below I’ve listed each of the fields on the Products tab and how they are used.

Website Attribute

If your Magento 2 instance manages a single website this field can remain blank. When managing multiple websites you can control which of your Akeneo products are assigned to which site by using a simple or multi select Akeneo attribute. The code for that attribute should be written into this field. The import will then properly assign products to the correct site on import.

Default Product Status

This dropdown controls what status a product will be set to when it is created in Magento 2. Once a product is created it will only change status in Magento if the product is changed from enabled to disabled in Akeneo. Products changed from disabled to enabled in Akeneo will not have their status changed in Magento. Note that if you’re not seeing product status change you may need to check your Filters.

Attribute Mapping

By default the Magento 2 connector will create a new Magento product attribute when it encounters a new Akeneo attribute code. If you want one of your Akeneo attributes to map to an existing Magento 2 attribute you will need to use this table. For example, you may have an attribute with code “product_name” in Akeneo. However, by default the name attribute in Magento 2 has the code “name”. The only way to get the “product_name” data to populate into the “name” field is to add these attribute codes to the Attribute Mapping table. The attributes “price”, “special_price”, and “cost” are not automatically mapped from Akeneo to their Magento counterparts. If you have a price in Akeneo that needs to populate the price in Magento you will have to add price/price to the Attribute Mapping table.

Metric Attributes

Because Magento does not have the concept of metric attributes, metrics get converted to text fields in Magento. By default these text fields will only be populated with the numeric value from Akeneo. For example, “25 ft.” would simply appear as “25”. If you want the unit to be included in the Magento text you will need to add the metric attribute code to the table and select “Yes” for the “Add metric unit to value” option.

Default Tax Class

This field allows you to choose a default tax class for your products coming from Akeneo. If running multiple sites each site can be given its own default tax class assignment. If no default tax class is selected in the table “None” will be assigned to all products.


Product model imports act differently from simple product imports. By default the product model in Akeneo is created as a configurable product in Magento 2. All variant products in Akeneo are created as simple product variations of the configurable product. The configurable product will only have Common level attributes assigned, while the simple products have both common and variant level attributes assigned. If you want to have different behavior for product model imports you must define that behavior in this table. There are 4 different types of custom behavior you can add: Mapping, First Variation value, SQL Statement, and Default value. The Mapping type works identically to the Attribute Mapping table above, but applies to the Common attributes of the product model. First Variation value causes the configuration product to get variant attributes populated based on the values of the first variant product. SQL Statement allows you to use SQL commands to do basic manipulations on common attributes with custom SQL code. Finally, Default value will provide a constant value to an attribute if it is not filled.

Akeneo association code for Related products

This field must contain the association code from Akeneo to assign Related products in Magento. The default value is “SUBSTITUTION”.

Akeneo association code for Upsell products

This field must contain the association code from Akeneo to assign Upsell products in Magento. The default value is “UPSELL”.

Akeneo association code for Cross-sell products

This field must contain the association code from Akeneo to assign Cross-sell products in Magento. The default value is “X_SELL”

Import Image Attributes

Use this option to choose whether or not to import images from Akeneo. If this field is set to “No” the 2 below tables will not be displayed. It is important to note that importing images can significantly decrease the speed of the product import process.

Akeneo Image Attributes

This list will contain the codes of image type attributes in Akeneo that must be imported.

Product Images Mapping

Here you can choose how each of your above image attributes gets represented in Magento. Magento has 4 image assignments: image, small_image, thumbnail, or swatch_image. If you wish for one of your Akeneo images to fill 2 or more of the Magento image assignments simply add multiple rows to the table, one for each desired image assignment.

Import File Attributes

Use this option to choose whether or not to import file type attributes from Akeneo. These files will be downloaded to the pub/media/akeneo_connector/media_files folder on your Magento server.

Akeneo File Attributes

This list will contain the different file type attributes that will be imported from Akeneo. The path to these files will be added to a corresponding text attribute on the product.

Does Akeneo data override content staging

If using Magento 2 Enterprise Edition you can set this option to “Yes” to cause product updates in Akeneo to override all product versions regardless of any scheduled changes. If set to “No” Akeneo updates will only impact the base version of the product.

Regenerate url rewrites

Lastly, if set to “Yes”, this option will create new url rewrites for your products each time they are updated. If set to “No” the url rewrites will only be generated on product creation. You’ll know the integration is working correctly when you see all of your products appearing in the Magento 2 catalog with the correct data populated into the correct fields.

Congratulations! You’ve successfully configured your connection, filtered your products, mapped your data, and run the jobs. Enjoy your new enrichment flow between Akeneo and Magento 2!

You May Also Like…