Akeneo PIM OroCommerce Connector

New maintainer

We would like to inform you about the recent transfer of repository maintenance responsibility from OroInc to Creativestyle. This transition aims to enhance the development and support of OroInc projects, providing a seamless experience for users and contributors.

• Starting from version 5.1, a new namespace and package name will be introduced as part of the changes.

Short overview

This extension allows you to connect OroCommerce Enterprise with Akeneo PIM Enterprise and use the latter’s rich capabilities for product information management with your OroCommerce-powered web store. Combine personalized B2B buying experience with compelling product experience to maximize your content marketing ROI and stay ahead of the B2B eCommerce game.

Description

Akeneo is a Product Information Management (PIM) solution that provides a single place to collect, manage, and enrich your product information, create a product catalog, and distribute it to your sales and eCommerce channels. In integration with OroCommerce, Akeneo makes it faster and easier to create and deliver compelling product experiences to your online customers.

With this extension, you will be able to sync the following data from Akeneo to OroCommerce:

• Attributes and attribute options
• Attribute families and attribute family groups
• Configurable products, simple products & all product data from supported attributes
• Categories and category trees

Compatibility

Connector	Status	OroCommerce	Akeneo
1.6	EOL	1.6	2.3, 3.2, 4.0*
3.1	EOL	3.1	2.3, 3.2, 4.0*
4.1	EOL	4.1	2.3, 3.2, 4.0*
4.2	EOL	4.2	3.2, 4.0, 5.0
5.0	2023	5.0	5.0+
5.1	2024	5.1	5.1+

** Akeneo supported using older client versions, new features are not available.**

Installation

1. Add composer package

version <= 5.0

composer require "oro/commerce-akeneo:5.0.*"

version >= 5.1

composer require "creativestyle/commerce-akeneo:5.1.*"

2. Follow Setup Guide

3. Configure Message Queue

** Recommended time limit option values is 30 seconds --time-limit=+30seconds

Schema

Make sure you don't have any pending Schema Update changes or entity and migration inconsistencies:

> php bin/console --env=prod doctrine:schema:update --dump-sql

[OK] Nothing to update - your database is already in sync with the current entity metadata.

OroCloud

Application Schema Update

Add temporary files cleanup using Scheduled Tasks

orocloud_options:
  schedule:
    clear_akeneo_temp_files:
      command: 'find /mnt/ocom/app/www/var/data/importexport/akeneo/ -type f -mtime +7 -delete'
      minute: '0'
      hour: '7'
      month: '*'
      monthday: '*/7'
      weekday: '*'

Dataset

Connector supports and tested on the next dataset:

• Locales: 4
• Currencies: 2
• Catalogs:
• • Levels: 4, children: 1000
• • Levels: 4, children: 1000
• Attribute Groups: 15 per Attribute Family
• Attributes: 400, 5% localizable, 2% scopable, 1% localizable and scopable, 100% usable in grid
• Attribute Families: 50, up to 100 Attributes per Attribute Family
• Products: 50000, including images

Setting up the Integration on the Oro Side

Create a new integration to start synchronizing data from Akeneo to OroCommerce.

1. In OroCommerce, navigate to "System > Integrations > Manage Integrations" in the main menu and click "Create Integration".

2. Select "Akeneo" for Type to load additional integration-related fields to finish the configuration.

3. In the "General" section, specify the name for the integration (e.g., Akeneo) and the following credentials required for successful connection to Akeneo API:

   • Akeneo URL - the address of your Akeneo account.
   • User ClientId - an identifier that authenticates your account. To create the ID, go to "System > Connections" in the Akeneo application.
   • User Secret - a key that is generated in "System > Connections" of the Akeneo application.
   • Akeneo Username - the name that the administrator will use to log into the Akeneo application.
   • Akeneo Password - the password that the admin will use to log into the Akeneo application.

4. Click "Check Akeneo Connection" once you have filled in all the settings fields. A corresponding message pops up when the connection fails/is successful.

5. If the connection is established successfully, the following fields get populated with the settings retrieved from Akeneo. In case of connection failure, the fields remain unchanged.

   • Channel - The Akeneo-specific data source. Each channel has a certain set of properties that define which data should be included in the channel. By selecting the desired channel, you request the data (products, currencies, or locales) associated with this specific channel. For example, the list of products or product descriptions in English may differ significantly from channel to channel.

     If some data of the selected channel has been changed after the initial synchronization, click "Refresh Channels" to reset the current configuration and retrieve the newly updated data from Akeneo.

   • Sync Products - The setting that defines which product type you want to synchronize. By default, we sync all products, bu you can choose to sync only the published ones by selecting the corresponding option.

   • Product Unit Attribute Name - Text attribute from Akeneo which contains product unit name.

   • Product Unit Precision Attribute Name - Numeric attribute from Akeneo which contains unit precision.

   • Currency - The currency options retrieved from Akeneo. If some currency is unavailable in OroCommerce, it will not be imported. Select one or several currencies for your products from the list. In case of no currency selected, the corresponding error message pops up that will require you to choose at least one currency.

     If the currency has been updated since the initial synchronization, click "Refresh Channels" to reset the current configuration and retrieve the newly updated data from Akeneo.

   • Locales - The setting that defines how the Akeneo locales on the left will be mapped to the OroCommerce ones on the right. It is possible to set any mapping behavior, such as EN. to EN., or FR. to EN.

     Note: Keep in mind that you cannot map the same locale multiple times or leave the field blank. So if you do not have the appropriate Oro locale to match the Akeneo locale, you can configure or enable it following the localization guide in the Oro documentation.

     If the locales have been updated since the initial synchronization, click "Refresh Channels" to reset the current configuration and retrieve the newly updated data from Akeneo.

   • Root Category - The root content node in the Oro application where you import the categories from Akeneo. You can create a specific parent category in the master catalog that would store all the categories uploaded from Akeneo. Select this category from the dropdown list.

   • Price List - The price list to which you will import the prices from Akeneo. This price list will help distinguish the Akeneo prices from those of other price lists provided that a product has several price options. Select the necessary pricelist from the dropdown list or create a new one directly from the integration page by clicking "+" next to the list.

   • Product Filter - The filter that enables you to embed the necessary code that would sync only the products you desire. As this filter is passed via API request, it must be filled in JSON format. More details on the format and filter options available for the products can be found in the Filters section of the Akeneo PIM documentation.

     Note: Your input is validated on the go. If you get a validation warning, ensure to correct the code or any issues reported.

   • Attribute Filter - The filter that enables you to limit the list of imported attributes. Values must be attribute code, separated with a semi-colon.

     Example: sku;descr;price;custom

     Note: if not defined before to save the integration, all attributes will be imported.

   • Image Attribute Filter - The filter that enables you to limit the list of imported image attributes. Values must be attribute code, separated with a semi-colon.

     Example: image;picture

     Note: The filter extends Attribute Filter, no need to list attribute codes twice.

   • Merge Images From Simple Products To Configurable Product: Copy images from Simple products to their Configurable parent products.

   • Multilevel Products - Enable or disable separate configurable products created from two levels product model (the 1st one a "root product model" and the 2nd one a "sub product model" in Akeneo).

   • Attributes Mapping - Mappings to copy values from Akeneo attributes to system or custom Product Attributes.

     Example 1: name:names; - name (text) attribute from Akeneo imported as Product Attribute Akeneo_name and additionaly copied to names Product Attribute.

     Example 2: description:descriptions; - description (text) attribute from Akeneo imported as Product Attribute Akeneo_description and additionaly copied to descriptions Product Attribute.

     Example 3: meta_titles:metaTitles; - meta_titles (text) attribute from Akeneo imported as Product Attribute Akeneo_meta_titles and additionaly copied to metaTitles Product Attribute.

     Note: Akeneo attribute and Product Attribute types should match (both Akeneo_name and names are Many to many to Localized fallback value entity).

   • Brand Reference Entity Code - Reference entity code to import as Brand entity and link to products.

   • Brand Attributes Mapping - Mappings to copy values from Akeneo attributes to system or custom Brand fields.

     Example: label:names; - label (text) attribute from Akeneo imported names Brand field.

     Note: It's not possible to add fields to Brand, existing fields are available only.

   • Connectors - The connectors that enable you to sync either the category or products or both by selecting/deselecting the relevant connector.

   • Default Owner - The Owner determines the list of users who can manage the integration and the data synchronized with it. All entities imported within the integration will be assigned to the selected user. By default, the field is prepopulated with the user creating the integration.

6. The Statuses field displays the log of the integration including the date and status of the connector execution, and the statistics it provides.

7. Once all the details of the integration have been specified, click "Save and Close". The integration has been successfully configured and will now appear in the integration grid.

Now you can deactivate, delete, cancel, or schedule synchronization by clicking the corresponding button in the top right corner.

Synchronizing Data

Usually, the integration data is synchronized automatically.

To start the synchronization manually, click "Schedule Sync" on the top right. Wait for data to synchronize.

Note: Keep in mind that the Akeneo OroCommerce integration implements only one-way synchronization which means that the changes from Akeneo will always override the conflicts with OroCommerce.

Click the "Check job progress" link to see the synchronization status.

Note: Every time you synchronize new product attributes from Akeneo, the Update Schema button appears on the top right of the Akeneo integration page and the Product Attributes page (Products > Product Attributes). Refresh the integration update page and click the Update Schema button to apply the changes and enable the product attributes. Otherwise, the attributes will be unavailable. Keep in mind that updating schema sets the Oro instance to the maintenance mode, so it is recommended to check if no critical processes are running before clicking the button.

Note: Click Update Cache button at System > Localization > Translations to get translation applied.

Once the schema update is complete, you can schedule another sync. To schedule full sync now, press the "Schedule Sync" button one more time.

Limitations

Because of the differences between Akeneo and OroCommerce, you should take into account a few limitations.

• When you create new attributes on the Akeneo side, they won't be saved to the product information in OroCommerce until the schema has been updated manually by pressing the Update Schema button on the integration page.
• When you add a select or multi-select attribute in Akeneo, the options won't be synchronized until the schema has been updated.
• Akeneo date field type can have a different value for every locale. The same behavior is not possible in OroCommerce. For this reason, it is imported as a localized fallback value.
• Akeneo multi-select fields can have different values per locale. In OroCommerce, all the values from the various locales are combined.
• Akeneo select fields can have different values per locale. In OroCommerce, the value from the default locale is used.
• In OroCommerce, products are validated which can cause some products to be skipped during import because the field requirements are different in Akeneo. Check the details in an integration status.
• SKUs in Akeneo can contain spaces. Change oro_product.sku.regex_pattern parameter to extend SKU validation.
• An attribute family is not required in Akeneo. In OroCommerce, an attribute family is always required.
• OroCommerce does not support multiple categories, only the first category listed is used for product assignment.
• OroCommerce does not support prices per currency, only the last price per currency listed is used for product assignment.
• Categories tree rebuild starts after categories import.
• Optional listeners are disabled by default. Please reindex data and recalculate prices manually.