How to import my PIM 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 the Assets management feature (Akeneo PIM Enterprise Edition only, for versions earlier than 4.0) or, since the version 100.5.0 of the Akeneo Connector, from the Asset Manager feature (Akeneo PIM Enterprise Edition only, version 4.0 or higher).

  • Akeneo Connector for Magento 2 Community Edition can retrieve images from the Image attributes only.
  • Akeneo Connector for Magento 2 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.

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

#How can I 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 Magento 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 Magento Image types:

Connector parameter Magento 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)

#How can I retrieve images from "Asset collection" attributes?

This feature is only available for the Akeneo Connector for Magento 2 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 Magento 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 Magento 2, you have to choose the asset system you want to use depending on your Akeneo PIM version :

Connector parameter Magento 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 Magento 2, 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 Magento - Image mapping based on Magento image type Magento - 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 Magento 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 Magento Text attribute code from the Asset Family to be used as alternative text for images in Magento for "Download images" mode

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

Connector parameter Magento - Image mapping based on Magento image type Magento - 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 Magento 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 Magento Text attribute code from the Asset Family to be used as alternative text for images in Magento for "Download images" mode

This setting will affect configurable products only.

Magento:

  • Image mapping based on Magento 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 Magento 2 product image gallery.

Since the 103.1.0 version of the Akeneo Connector for Magento 2, 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 Magento 2 product attribute.

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

The Asset Manager >= v4.0 System for Akeneo PIM 4.0 or higher assigns asset images to your Magento 2 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 Magento 2.

If you want to use this feature, make sure that your Magento 2 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 Magento 2, 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 Magento 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.

#Asset collection configuration examples:

Import multiple attributes from the same asset to different image types:

Magento - Image mapping based on Magento image type Magento - 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:

Magento - Image mapping based on Magento image type Magento - 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:

Magento - Image mapping based on Magento image type Magento - 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:

Magento - Image mapping based on Magento image type Magento - 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:

Magento - Image mapping based on Magento image type Magento - 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

#How can I define the "base" image?

#With Image attributes

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

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

#With Asset collection attributes

Since the 103.1.0 version of the Akeneo Connector for Magento 2, the base image will be defined by the "Image mapping based on Magento image type" column value for you asset collection attributes.

Before that, Akeneo Connector for Magento 2 takes the first image of the first configured asset collection attribute to define which image will be the base image in Magento 2 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 Magento 2 assigns the attributes defined in the Product Images Mapping and Image mapping based on Magento image type column for you asset collection attributes to each corresponding Magento 2 image types for your product.

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

#So, can I use "Image" AND "Asset collection" simultaneously?

Yes (since the 100.2.1 version of the Akeneo Connector for Magento 2)! Please refer to this list to understand how Akeneo Connector will import your images:

  • Import Image Attributes set to Yes and Import Asset Attributes set to No. Only specified media attributes will be imported. Magento Image types will follow your mapping specified in Product Images Mapping.

  • Import Image Attributes set to No and Import Asset Attributes set to Yes. Only your specified assets collections will be imported. The image types will be defined by the Image mapping based on Magento image type column value for you asset collection attributes.

  • Import Image Attributes set to Yes and Import Asset Attributes set to Yes and an empty Product Images Mapping Your specified media attributes AND asset collections will be imported. The image types will be defined by the Image mapping based on Magento image type column value for you asset collection attributes.

  • Import Image Attributes set to Yes and Import Asset Attributes set to Yes and a mapping in Product Images Mapping Your specified media attributes AND asset collections will be imported. Magento Image types follow your mapping specified in Product Images Mapping and Image mapping based on Magento image type column value for you asset collection attributes. Only the Image types you specified will be filled.

Be curious! Take a look at these related articles

Where can I find the connector configuration? >

Configure your PIM API >

How can I filter PIM products I want to import? >

How to configure my categories? >

How to configure products? >

How to import my PIM Reference Entities? >