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?
It's important to note that the Community Edition of the Akeneo Connector does not handle reference entities since "Reference entities" are a specialized feature exclusive to the PIM Enterprise Edition.
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", we decided to map 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:
| Connector parameter title | Connector default options |
|---|---|
| Get reference entities attributes | Yes or No(default) |
Depending on the configuration, different attributes are created in Adobe Commerce :
| Connector configuration | Attribute(s) created in Adobe Commerce |
|---|---|
| No (default) | Reference entity label attribute |
| Yes | Reference entity label attribute AND Reference entity data attribute |
Reference entity label attribute - data transferred
The Reference entity label attribute is a simple/multi-select attribute that contains all localized records labels of the reference entity as options.
The attribute is a simple or a multi-select attribute depending on the Akeneo attribute type :
| Akeneo attribute type | Adobe Commerce attribute type |
|---|---|
| Reference entity single link | Select |
| Reference entity multiple links | Multi-select |
Reference entity label attribute is imported by the Attribute Import job and options by the Option Import job.
Only Reference entity single link can be used as a configurable axis for Configurable Products.
Reference entity data attribute - data transferred
The Reference entity data attribute is a text area attribute that contains all data from Reference entities records assigned to your product (in JSON format).
[
{
"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"
}
]Reference entity data attribute is created by the Attribute Import job and data is assigned to products by the Product Import job.
You need to create your own methods to parse and use the data from this attribute.
The attribute code of the reference entity data attribute is the same than the reference entity label attribute, but suffixed with _data.
This mapping operation therefore duplicates the data of PIM reference entities at the product level in Adobe Commerce.
Please ensure that the amount of data generated does not slow down the synchronization of your data too much.
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 :
- Open Adobe Commerce CATALOG menu
- Click on Products
- Use the search engine to find your product
- Open your product
- 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 :
- Open Adobe Commerce STORES menu
- Click on Product in Attributes
- 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.