Introduction

Some information are shared between different products, such as care instructions, or colors or even brands. This data can be complex to manage because it has its own attributes (e.g. a label, a logo, a description or photos).  
This information may have dedicated pages on one's e-commerce website (e.g. a webpage describing a brand) or their information may be used to enrich product pages (e.g. the logo of a brand). 

 To handle such complexity, Akeneo PIM Enterprise Edition has a feature called reference entities. Reference Entity regroups several records. Please refer to the documentation for a detailed explanation of what reference entities are and how they work: What is a reference entity?

Mapping

Reference entities attributes

Pre-requisite

Available since the 100.2.1 version of the Akeneo Connector for Adobe Commerce.

Before being able to map your reference entities in the connector, you should ensure that your product family template within the PIM, includes the following attribute types:

• Reference entity single link
• Reference entity multiple links

This step is essential to link reference entities records to products in the PIM.

Reference entity label attribute and data attribute

As Adobe Commerce does not have anything similar to PIM "reference entity", the connector is  mapping the reference entities at the product level by default.

In the connector configuration page, under Attributes, you can retrieve reference entities with the following parameters:

Depending on the configuration, different attributes are created in Adobe Commerce :

 
 [
 {
 "simpleselect": 
     "label": "I am a simple select title",
     "value": "Hello world",
 ],
 "magento_option_id": "30"
 },

 [
 {
 "label": "Record Label",
 "attribute_1": "Record Attribute 1 Value",
 "attribute_image": "akeneo_connector/reference_entities/records/path/to/image.jpg",
 "attribute_multiselect": [
 "Record Attribute Multiselect Option 1",
 "Record Attribute Multiselect Option 2"
 ],
 "magento_option_id": "30"
 },
 {
 "label": "Second Record Label",
 "attribute_1": "Second Record Attribute 1 Value",
 "attribute_image": "akeneo_connector/reference_entities/records/path/to/image.jpg",
 "attribute_multiselect": [
 "Second Record Attribute Multiselect Option 1",
 "Second Record Attribute Multiselect Option 2"
 ],
 "magento_option_id": "31"
 }
 ]

Link "Reference entity label attribute" and "Reference entity data attribute"

You can link the Reference entity label attribute and the Reference entity data attribute in your custom code by using the magento_option_id value inside the Reference entity data attribute JSON content.

magento_option_id value is corresponding to the Magento 2 option_id inside the eav_attribute_option table.

You can also use the localized label of your Reference entity label attribute in order to match the label value contained inside the Reference entity data attribute JSON content.

Product swatches

Available since the 103.4.0 version of the Akeneo Connector for Adobe Commerce.

You can map reference entities with “Text Swatch” or “Visual Swatch” attribute type in Adobe Commerce, which allows you to import colors ( hexadecimal) or images.

Check this article to know more : Mapping products

Find my PIM Reference entities in Adobe Commerce

Reference entities attributes

As explained above you can import reference entities as Reference entity label attribute or Reference entity data attribute. In this case, to find your data you need to go in your product :

1. Open Adobe Commerce CATALOG menu
2. Click on Products
3. Use the search engine to find your product
4. Open your product
5. Click on the Akeneo section and look for the reference entities attributes

 

 

Reference entities as Product swatches

As explained above you can import reference entities as product swatches. In this case, to find your data you need to go to your PIM attributes :

1. Open Adobe Commerce STORES menu
2. Click on Product in Attributes
3. Use the search engine to find the reference entity attribute used as product swatch

 

 

Reference entities medias

You can find your Reference entities medias in this directory: pub/media/akeneo_connector/reference_entities/records/.

Medias are imported by the Product Import job.