Filtering and mapping asset

Summary

Introduction

We truly believe that a product sheet has no real impact without any media. Most of the products sold on the Internet are described with several images, videos, pdf documents, etc. In the PIM you can either use image attributes or The Asset Manager in EE editions. The asset manager is an efficient way to manage the assets linked to your products/product models inside the PIM. Refer to this article for more information 

Import Asset files

Available since the 100.6.0 version of the Akeneo Connector for Adobe Commerce and for Akeneo Edition 4.0 and greater.

You can import files from assets into Adobe Commerce.

Connector parameter Adobe Commerce information
Import New File Asset Yes or No

If set to No, no new files will be downloaded but the already imported attributes won't be erased.

All files will be downloaded in the 'pub/media/akeneo_connector/asset_files/' folder

 
Connector parameter File Asset Collection Attribute
Akeneo Asset Manager File Attributes List your Akeneo PIM File Asset Collection attribute codes

As Adobe Commerce cannot handle file upload attributes, the connector will download Akeneo asset files and insert the link into the attribute, formatted as JSON.

JSON example:

{
 "asset_file_1": "akeneo_connector/asset_files/f/i/file-1.pdf",
 "asset_file_2": "akeneo_connector/asset_files/f/i/file-2.pdf"
 }
 

The connector will only import asset files with a main media of the media type "PDF" or "Other".

 

The connector will import asset files from both media file and media link attributes.

 

The localizable and scopable dimensions of your Akeneo Asset Collection File attribute and the Akeneo Asset Family main media attribute will be automatically managed by the connector.

 

Since the 100.6.0 version of the Akeneo Connector for Adobe Commerce, the connector will transform asset collection attributes to text areas in Adobe Commerce in order to handle JSON content for asset collection file attributes.

 

If you already imported an asset collection file attribute before upgrading the connector to version 100.6.0, you will have to delete the previously imported attribute and import it again in order to transform it into a text area.

 

Since the 101.0.2 version of the Akeneo Connector for Adobe Commerce, the connector manages the prefix and the suffix defined on the main media attribute of your Akeneo file asset family.

 

Prefixes and suffixes are only available for external media link attributes.

Since the 101.6.0 version of the Akeneo Connector for Adobe Commerce, you can import all attributes from files assets family into Adobe Commerce when enabling the following parameter:

Connector parameter Adobe Commerce information
Enable Download of All File Asset Attributes Yes or No

If set to yes, the JSON format will become:

{
 "asset_file_1": {
 "label": "File 1",
 "file": "akeneo_connector/asset_files/f/i/file-1.pdf",
 "description": "File 1 description",
 "tags": "Tag 1"
 },
 "asset_file_2": {
 "label": "File 2",
 "file": "akeneo_connector/asset_files/f/i/file-2.pdf",
 "description": "File 2 description",
 "tags": "Tag 2"
 }
 }
 
Connector parameter Adobe Commerce information
Download Akeneo External File Asset Link Yes or No

This parameter allows you to choose whether to locally download or not the Akeneo file assets with the media type "Media Link".

If set to No, the Akeneo file asset links will be added to the JSON.

If set to Yes, the Akeneo external file assets will be downloaded to Adobe Commerce and the local path will be added to the JSON. Also, if set to Yes, the Akeneo External File Asset Link Download parameter will be displayed.

Setting this option to Yes might affect the performance of the import due to the downloading time of the Akeneo file assets.

 
Connector parameter Adobe Commerce information
Akeneo External File Asset Link Download Always download all assets or Download only assets with different filename

As it is not possible to detect that an external file has been modified, this parameter allows you to choose between two download modes for assets with a main media attribute of "Media Link" type:

  • Always download all assets: This option will always download all assets with an external media link.
    • This option will handle any changes on your external assets but might slow down your imports.
  • Download only assets with different filename: This option will not download previously downloaded assets from an external media link based on their filename.
    • This option will not be able to import an external asset that has been modified but that keeps the same filename than a previously imported asset.

Import Asset videos

Available since the 100.6.0 version of the Akeneo Connector for Adobe Commerce and for Akeneo Edition 4.0 and greater.

You can import video links from assets into Adobe Commerce. Please consider that URLs management is not native in Adobe Commerce and then the related information will be stored in a JSON format.

Connector parameter Asset Collection Attribute Description Asset Attribute Used As Preview Title Asset Attribute Used As Preview Image Import Mode
Akeneo Asset Manager Video Attributes List your Akeneo PIM Video Asset Collection attribute codes Text attribute code from the Asset Family to be used as video description in Adobe Commerce Text attribute code from the Asset Family to be used as video title in Adobe Commerce Image attribute code from the Asset Family to be used as preview image in Adobe Commerce Import in video gallery or Import attributes as JSON
 

As Adobe Commerce cannot handle video binary files, the connector will only import assets with a main media of the media type "Youtube" or "Vimeo"

 

The preview images for asset videos are mandatory as Adobe Commerce needs an image in order to display videos on the product page

The title is not mandatory for the connector to import videos, but it is highly recommended to configure it as Adobe Commerce is expecting one in the admin product page

 

Videos will always be inserted at the end of the gallery image in Adobe Commerce. If there are multiple videos for the same product, the order from Akeneo will be respected in Adobe Commerce image gallery.

 

The localizable and scopable dimensions of your Akeneo Asset Collection Video attribute and the Akeneo Asset Family main media, description, title and preview image attribute will be automatically managed by the connector

 

Since the 101.0.2 version of the Akeneo Connector for Adobe Commerce, the connector manages the prefix and the suffix defined on the main media attribute and on the preview image attribute of your Akeneo video asset family.

Prefixes and suffixes are only available for external media link attributes.

 

Since the 101.8.0 version of the Akeneo Connector for Adobe Commerce, you can choose the import mode for your Akeneo Asset Videos.

If set to "Import in video gallery", the video link and the associated description, title and preview images will be imported in Adobe Commerce video gallery.

If set to "Download attributes as JSON", asset attributes will be imported as JSON in the corresponding Adobe Commerce product attribute.

 

Import images from image attributes and asset collection attributes

What "images" are we talking about exactly ?

Akeneo PIM Enterprise Edition has 2 ways to store images for your products.

Images can be stored either with several Image attributes and/or with the Asset collection attribute. It points to one or more images from either :

Feature Akeneo PIM Edition
the Assets management feature Akeneo PIM Enterprise Edition only, for versions earlier than 4.0
the Asset Manager feature Available since the version 100.5.0 of the Akeneo Connector for Adobe Commerce
Akeneo PIM Enterprise Edition only, version 4.0 or higher

 

  • Akeneo Connector for Adobe Commerce Community Edition can retrieve images from the Image attributes only.
  • Akeneo Connector for Adobe Commerce Enterprise Edition can retrieve images from the Image attributes and from the Asset collection attributes (you can use multiple image attributes and multiple asset collection attributes).

There is an 80-character limitation when the connector renames images and asset files from Akeneo.

There is also a hash composed of four random characters at the end of the file name to ensure the uniqueness of the file.

 

Adobe Commerce will manage the standard image web format: .jpeg, .jpg, .png and gif

 

Retrieve images from the "Image" attributes

In the connector configuration page, in Products, you can retrieve images from the PIM Image attributes thanks to the following parameters:

First, select Yes if you want to import images:

Connector parameter Adobe Commerce information
Import Media File (Akeneo Connector < 100.4.2) Yes or No
Import Image Attributes (Akeneo Connector >= 100.4.2) Yes or No

Then, list all your PIM Image attributes:

Connector parameter PIM information
Akeneo Attributes for Image Gallery PIM Image attribute ID

Finally, define the mapping between the PIM Image attribute and the Adobe Commerce Image types:

Connector parameter Adobe Commerce information PIM information
Product Image Association (Akeneo Connector < 100.4.2) image(image) PIM Image attribute ID
Product Images Mapping (Akeneo Connector >= 100.4.2) small_image(small_image)  
thumbnail(thumbnail)  
swatch_image(swatch_image)  

Since the version 103.3.0 of the Akeneo Connector for Adobe Commerce, you can import localizable / scopable / localizable and scopable image attributes in Adobe Commerce. The corresponding images will be assigned per store view inside the products.

 

Retrieve images from "Asset collection" attributes

This feature is only available for the Akeneo Connector for Adobe Commerce Enterprise Edition.

 

If, for your images, you use the Asset collection attribute instead of the PIM Image attribute, in the connector configuration page, in Products, select Yes to retrieve images from Asset collection attributes:

Connector parameter Adobe Commerce information
Import Asset Files (Akeneo Connector < 100.4.2) Yes or No
Import Asset Attributes (Akeneo Connector >= 100.4.2) Yes or No

Since the version 100.5.0 of the Akeneo Connector for Adobe Commerce, you have to choose the asset system you want to use depending on your Akeneo PIM version :

Connector parameter Adobe Commerce information
Akeneo Asset System Asset Manager <= v3.2 or Asset Manager >= v4.0

For Akeneo PIM earlier than version 4.0, choose 'Asset Manager <= v3.2'.

For Akeneo PIM version 4.0 or higher, choose 'Asset Manager >= v4.0'.

 

For Akeneo PIM earlier than 4.0 - Asset Manager <= v3.2 System

Connector parameter Akeneo Attribute
Akeneo Asset Attributes List your Akeneo PIM Asset Collection attribute codes

For Akeneo PIM 4.0 or higher - Asset Manager >= v4.0 System

Since the 103.1.0 version of the Akeneo Connector for Adobe Commerce, there is two seperate settings for simples products and configurable products that allows to map image type and to import multiple image attributes from the same asset:

Connector parameter Adobe Commerce - Image mapping based on Adobe Commerce image type Adobe Commerce - Hide image from product gallery Akeneo - Asset collection attribute code Akeneo - Image mapping based on asset family attribute code Akeneo - Alternative text based on asset family attribute code
Akeneo Asset Manager Product Image Attributes for Gallery Select every Adobe Commerce image type to map with the asset image Yes or No to hide the imported image from the product gallery List your Akeneo PIM Asset Collection attribute codes Attribute code from the Asset Family to be imported as image in Adobe Commerce Text attribute code from the Asset Family to be used as alternative text for images in Adobe Commerce for "Download images" mode

This setting will affect simple, grouped, and virtual products.

Connector parameter Adobe Commerce - Image mapping based on Adobe Commerce image type Adobe Commerce - Hide image from product gallery Akeneo - Asset collection attribute code Akeneo - Image mapping based on asset family attribute code Akeneo - Alternative text based on asset family attribute code
Akeneo Asset Manager Configurable Product Image Attributes for Gallery Select every Adobe Commerce image type to map with the asset image Yes or No to hide the imported image from the product gallery List your Akeneo PIM Asset Collection attribute codes Attribute code from the Asset Family to be imported as image in Adobe Commerce Text attribute code from the Asset Family to be used as alternative text for images in Adobe Commerce for "Download images" mode

This setting will affect configurable products only.

 

Adobe Commerce:

  • Image mapping based on Adobe Commerce image type: Select the image type to be associated with the Asset. If no image type is selected, the Asset will be added to the product image gallery without any type.
  • Hide image from product gallery: If yes, the Assets will be hidden in the product image gallery.

Akeneo:

  • Asset collection attribute code: Code of the asset collection attribute in Akeneo.
  • Image mapping based on asset family attribute code: Code of the asset family attribute in Akeneo to be used as product image. If empty, the main_media will be used.
  • Alternative text based on asset family attribute code: Code of the asset family attribute in Akeneo to be used as alternative text. Can be empty.

If "Asset Attribute Used As Image" is empty, the attribute defined as "Main media" in the Asset Family will be used.

 

Asset images will be downloaded and added to the Adobe Commerce product image gallery.

 

Since the 103.1.0 version of the Akeneo Connector for Adobe Commerce, a separate settings allows you to list the image asset collection you want to import as JSON:

Connector parameter Asset Collection Attribute
Akeneo Asset Manager Image attribute import as JSON List your Akeneo PIM Asset Collection attribute codes

You cannot import an asset collection attribute as JSON if it is already used as "Akeneo Asset Manager Product Image Attributes for Gallery" or "Akeneo Asset Manager Configurable Product Image Attributes for Gallery".

 

Asset attributes will be imported as JSON in the corresponding Adobe Commerce product attribute.

This setting can be used to fetch "Media link" image attributes from your assets into Adobe Commerce without downloading the images.

 

The Asset Manager >= v4.0 System for Akeneo PIM 4.0 or higher assigns asset images to your Adobe Commerce stores depending on the scopable and localizable values of the asset collection attribute in your products. It also depends on the scopable and localizable values of your assets in the Asset Manager. All images will be imported in the product gallery, but the images not assigned to specific locales or channel in your Akeneo PIM will be disabled at the store view level in Adobe Commerce.

If you want to use this feature, make sure that your Adobe Commerce image attributes are configured with the "Store View" scope.

 

For Akeneo PIM version 4.0 or higher, your family main media type should be Image.

 

The connector imports Akeneo PIM asset images in the same order as defined in the PIM at the asset collection attribute type level.

 

Since the 101.0.2 version of the Akeneo Connector for Adobe Commerce, the connector manages the prefix and the suffix defined on the main media attribute of your Akeneo image asset family.

 

Prefixes and suffixes are only available for external media link attributes.

Connector parameter Adobe Commerce information
Akeneo External Asset Link Download Always download all assets or Download only assets with different filename

As it is not possible to detect that an external image has been modified, this parameter allows you to choose between two download modes for assets with a main media attribute of "Media Link" type:

  • Always download all assets: This option will always download all assets with an external media link.
    • This option will handle any changes on your external assets but might slow down your imports.
  • Download only assets with different filename: This option will not download previously downloaded assets from an external media link based on their filename.
    • This option will not be able to import an external asset that was modified but with the same filename as a previously imported asset.

Since the 103.2.0 version of the Akeneo Connector for Adobe Commerce, you can configure the chunk size of Asset Image insertion under the "Advanced" section:

Connector parameter Adobe Commerce information
Enable Asset Import Chunk Yes or No
Connector parameter Adobe Commerce information
Asset Import Chunk Size Number of assets per insert

For large catalogs and/or small servers, you can use this parameter to adjust the chunk insertion by X image assets in order to avoid memory overflow or timeouts

 

Asset collection configuration examples

Import multiple attributes from the same asset to different image types

Adobe Commerce - Image mapping based on Adobe Commerce image type Adobe Commerce - Hide image from product gallery Akeneo - Asset collection attribute code Akeneo - Image mapping based on asset family attribute code Akeneo - Alternative text based on asset family attribute code
Image (image) No product_images image label
Small Image (small_image) No product_images small_image label
Thumbnail (thumbnail) No product_images thumbnail label
 
 

Import single asset collection attribute to multiple image types

Adobe Commerce - Image mapping based on Adobe Commerce image type Adobe Commerce - Hide image from product gallery Akeneo - Asset collection attribute code Akeneo - Image mapping based on asset family attribute code Akeneo - Alternative text based on asset family attribute code
Image (image), Small Image (small_image), Thumbnail (thumbnail) No product_images media label
 
 

Import multiple asset collection attribute to multiple image types

Adobe Commerce - Image mapping based on Adobe Commerce image type Adobe Commerce - Hide image from product gallery Akeneo - Asset collection attribute code Akeneo - Image mapping based on asset family attribute code Akeneo - Alternative text based on asset family attribute code
Image (image), Small Image (small_image), Thumbnail (thumbnail) No product_images media label
Swatch Image (swatch_image) No color_images media label
 
 

Import hidden asset images to custom image type

Adobe Commerce - Image mapping based on Adobe Commerce image type Adobe Commerce - Hide image from product gallery Akeneo - Asset collection attribute code Akeneo - Image mapping based on asset family attribute code Akeneo - Alternative text based on asset family attribute code
Brand Image (brand_image) Yes brand media label
 
 

Import asset images to the product gallery without specific image type

Adobe Commerce - Image mapping based on Adobe Commerce image type Adobe Commerce - Hide image from product gallery Akeneo - Asset collection attribute code Akeneo - Image mapping based on asset family attribute code Akeneo - Alternative text based on asset family attribute code
Empty No product_gallery_images media label
 
 

Define the "base" image

With Image attributes

Akeneo Connector for Adobe Commerce assigns the attributes defined in the Product Images Mapping mapping to each corresponding Adobe Commerce image types for the product.

If the mapping is not specified for the image type, no images will be set as base image in Adobe Commerce.

 
 

With Asset collection attributes

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

The base image will be defined by the "Image mapping based on Adobe Commerce image type" column value for you asset collection attributes.

Before that, Akeneo Connector for Adobe Commerce takes the first image of the first configured asset collection attribute to define which image will be the base image in Adobe Commerce for your product.

In Akeneo PIM, please be aware that you can change the image order for an asset collection attribute with a simple drag & drop action.

 
 
 

With Image AND Asset collection attributes

If specified, Akeneo Connector for Adobe Commerce assigns the attributes defined in the Product Images Mapping and Image mapping based on Adobe Commerce image type column for you asset collection attributes to each corresponding Adobe Commerce image types for your product.

If the mapping is not specified, the images will be added to the gallery, without specific types.

 
 

Use "Image" AND "Asset collection" simultaneously

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

 Please refer to this list to understand how Akeneo Connector will import your images:

Import Image Attributes Import Asset Attributes Behavior
Yes No Only specified media attributes will be imported. Adobe Commerce Image types will follow your mapping specified in Product Images Mapping.
No Yes Only your specified assets collections will be imported. The image types will be defined by the Image mapping based on Adobe Commerce image type column value for you asset collection attributes.
Import Image Attributes Import Asset Attributes Product Images Mapping Behavior
Yes Yes Empty Your specified media attributes AND asset collections will be imported. The image types will be defined by the Image mapping based on Adobe Commerce image type column value for you asset collection attributes.
Yes Yes Filled Your specified media attributes AND asset collections will be imported. Adobe Commerce Image types follow your mapping specified in Product Images Mapping and Image mapping based on Adobe Commerce image type column value for you asset collection attributes. Only the Image types you specified will be filled.