How to import my PIM images?

#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.

Please note that since the version 100.3.1 of the Akeneo Connector for Magento 2 and due to a compatibility issue with Magento 2.3.3, there is an 80-character limitation when the connector renames images and asset files from Akeneo. It also adds a hash composed of four random characters at the end of the file name to ensure the uniqueness of the file.

Also note that all existing product images will be renamed during import after updating to the 100.3.1 version of the Akeneo Connector for Magento 2.

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 version 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

Connector parameter Akeneo Attribute Asset Attribute Used As Image Asset Attribute Used As Alt Text Import Mode
Akeneo Asset Manager Image Attributes List your Akeneo PIM Asset Collection attribute codes Attribute code from the Asset Family to be imported as image in Magento for "Download images" mode Text attribute code from the Asset Family to be used as alternative text for images in Magento for "Download images" mode Download images or Import attributes as JSON

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

If "Import mode" is set to "Download images", asset images will be downloaded and added to the Magento 2 product image gallery.

If "Import mode" is set to "Import attributes as JSON", asset attributes will be imported as JSON in the corresponding Magento 2 product attribute. This mode 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.

Since the version 100.5.3 of the Akeneo Connector for Magento 2, the Asset Manager >= v4.0 System manages the scopable and localizable dimension of your assets in the Asset Manager. Before that version, the scopable and localizable dimension of your assets in the Asset Manager were not handled.

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.

Since the 101.3.0 version of the Akeneo Connector for Magento 2, you can choose to set the first Asset Collection Image as the Magento 2 "swatch image" type:

Connector parameter Magento information
Use First Asset Collection Image As Swatch Yes or No

If set to yes, the first asset of the first asset collection found in "Akeneo Asset Manager Image Attributes" will be set as Swatch Image for your products.

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 than a previously imported asset.

#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

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 you could 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 mapping to each corresponding Magento 2 image types for your product.

If the mapping is not specified, all Magento 2 Image types ("image", "small_image" and "thumbnail") will be assigned to the first image of the first configured asset collection attribute.

#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. "Image", "small_image" and "thumbnail" Magento Image types will be assigned to the first file imported.

  • 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. "Image", "small_image" and "thumbnail" Magento Image types will be assigned to the first image of the first asset collection.

  • 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. Only the Image types you specified will be filled.

As you cannot choose which asset from an asset collection attribute is assigned to which Magento 2 Image type, "swatch_image" type can only be linked with an image attribute from Akeneo PIM.

The behavior is the same for Akeneo PIM below version 4.0 (Asset Manager <= v3.2 System) AND for Akeneo PIM 4.0 or higher (Asset Manager >= v4.0 System)

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? >