Installation

Summary

Introduction

The installation of the Akeneo Connector for Adobe Commerce is a technical process that should be handled by individuals or teams with a strong technical background and experience in setting up software integrations.

The Akeneo Connector for Adobe Commerce is available in two distinct versions:

  1. Akeneo Connector for Adobe Commerce Community Edition
  2. Akeneo Connector for Adobe Commerce Enterprise Edition

Please be aware that each version features its own installation process, tailored to its specific characteristics and requirements. Choose the edition that aligns with your business needs and follow the corresponding installation procedure for a seamless setup.

To ensure a successful installation of the connector, we strongly recommend enlisting the expertise of a technical resource with a proven track record of Adobe Commerce skills and Akeneo PIM knowledge. This individual or team should have a demonstrated proficiency in both Adobe Commerce and the specifics of the connector to carry out the installation effectively. Their experience and knowledge will be instrumental in setting up the connector correctly and maintaining its optimal performance. For added convenience and to streamline the installation process, Akeneo offers a Professional Service Assistance option. Please reach out to your Customer Success Manager (CSM) for further details and assistance.

 

Getting the connector

Enterprise Edition

Akeneo Connector for Adobe Commerce (Enterprise Edition) is compatible with Akeneo PIM Enterprise Edition. This version is officially supported and maintained by Akeneo.

To acquire the Enterprise Edition of the connector, please reach out to us through the app store or directly by contacting your dedicated CSM. 

We will provide you with access to our Private GitHub repository, where the supported version of the connector is hosted. Our Akeneo teams will guide you through the installation process via our Partner Portal and assist you in leveraging Akeneo Support for your enterprise needs.

 
 

Community Edition

Akeneo Connector for Adobe Commerce (Community Edition) is designed for compatibility with both Akeneo PIM Community and Enterprise Editions, but it does not support Akeneo PIM Enterprise Edition-specific features.

Please note that this free, open-source version of Akeneo Connector for Adobe Commerce does not include official support and maintenance from Akeneo.

 

You can access this version directly from the Adobe Commerce Marketplace.

 
 

Installing the connector on Akeneo PIM

Enterprise Edition

Installation of "Akeneo Connector for Adobe Commerce Enterprise Edition"

Before you can begin the installation of the Akeneo Connector for Adobe Commerce Enterprise Edition, make sure you meet the following prerequisites.

Pre-requisites

the Akeneo Connector for Adobe Commerce code access is hosted on the Project Console of the Akeneo portal. Before you can begin the installation of the Akeneo Connector for Adobe Commerce Enterprise Edition, make sure you meet the following project management prerequisites:

  1. Ensure that you have access to the connector within the Akeneo Portal (if you have not already done so).
  2. Create a developer profile within your organization, who will be responsible for the installation. Grant this developer access to the Project Console.
  3. Confirm that your designated developer has declared their SSH key within their profile on the Akeneo portal and has been granted access rights to the Enterprise Repository.
  4. It's crucial that your developer connects to your Adobe Commerce server using the same SSH key that was configured in the Akeneo portal. Refer to the Adobe Commerce documentation for guidance on setting up your SSH key in Adobe Commerce. Please read the Adobe Commerce documentation on how to configure your SSH key in Adobe Commerce.

Once you've met these prerequisites, follow these steps to install the module using Composer:

Configure the repository for the module

 composer config repositories.magento2-connector-enterprise '{"type": "vcs", "url": "ssh://git@distribution.akeneo.com:443/magento2-connector-enterprise"}'

Install the module

 composer require "akeneo/magento2-connector-enterprise" "103.*"

Enable the module in Adobe Commerce

 php bin/magento module:enable Akeneo_Connector

Check and update the database setup

 php bin/magento setup:db:status
 php bin/magento setup:upgrade

Flush the Adobe Commerce cashes

php bin/magento cache:flush
 
 

Community Edition

Install "Akeneo Connector for Adobe Commerce Community Edition"

Because the connector is a module for Adobe Commerce, you must connect with SSH and have the correct access to your Adobe Commerce server to install the connector.

Install the module with Composer as follows

 composer require akeneo/module-magento2-connector-community

Enable the module in Adobe Commerce

 php bin/magento module:enable Akeneo_Connector

Check and update database setup

 php bin/magento setup:db:status
 php bin/magento setup:upgrade

Flush Adobe Commerce caches

 php bin/magento cache:flush
 
 

Configuring your PIM API

Before proceeding with the setup of the Akeneo Connector for Adobe Commerce, it is imperative to generate a "client ID" and "secret" pair within your PIM to enable the API connection. For detailed instructions on this process, please consult our dedicated documentation.

Please refer to our specific documentation to do so.

Key Information to Note:

  1. Your PIM URL (ex: https://mypim.cloud.akeneo.com)
  2. Your PIM API Client ID and Secret
  3. Your PIM User dedicated to the use of the API (Username and Password).

Installing the connector on Adobe Commerce cloud environment

Installing the extension with the deploy key

Installing the Akeneo Connector for Adobe Commerce on an Adobe Commerce Cloud environment is a straightforward process. You can follow the standard Adobe Commerce documentation for installing an extension in an Adobe Commerce Cloud environment.

Additionally, it's essential to enable the deploy key of your Adobe Commerce Cloud environment within the Akeneo Portal to ensure a secure and seamless connection. To get your Adobe Commerce Cloud environment deploy key, go to your Adobe Commerce Cloud account:

  1. Enable Adobe Commerce Cloud Deploy Key: Within your Adobe Commerce Cloud account, locate your Adobe Commerce Cloud environment's deploy key by following these steps:
  2. Copy the Deploy Key: Once you've accessed the Deploy Key tab, copy the deploy key, as you will need it to access external private code repositories during the build process.
  3. Enable the Key in the Akeneo Portal: To finalize the setup, follow the provided guide within the Akeneo Portal to enable the Adobe Commerce Cloud environment's deploy key. This step ensures that the Akeneo Connector can securely access the necessary resources during the installation and synchronization processes.

Configuring the connector with your PIM API information

Within the  connector configuration page, navigate to the "Akeneo API configuration" section and input the following parameters with the PIM information collected earlier:

Connector parameter PIM information
Akeneo base URL PIM URL
Akeneo user name PIM user Username
Akeneo password PIM user Password
Akeneo API client ID PIM API Client ID
Akeneo API client secret PIM API Secret

To verify the functionality of the connection, simply click on the "Test" button. If the connection is successful, you should receive a confirmation message stating, "The connection is working fine." This indicates that the connection is operating as expected.

Optimize the performance of the PIM API connection

In the connector configuration page, under the "Akeneo API configuration" section, you have the option to adjust the API pagination limit. By default, this limit is set to 100. Feel free to modify this parameter to optimize the import speed of the Connector according to your specific requirements and preferences.

Configuring your Akeneo Edition

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

Within the connector configuration panel, make sure to specify the Akeneo Edition of your Akeneo platform. This step is vital for ensuring accurate integration between the systems. This configuration will activate and display features, depending on your Akeneo Edition.

Connector parameter PIM information
Akeneo Edition 3.2, Between 4.0.0 and 4.0.62, 4.0.62 or greater, 5.0 or greater, Serenity Edition, Growth Edition

To find your Akeneo Edition and Version, simply navigate to the bottom of the dashboard page of your Akeneo platform. This information is conveniently displayed there for reference.

 

Setting up on a pre-existing Adobe Commerce

To ensure a seamless data transfer and connection between the two systems, there are crucial preparatory steps to consider before configuring your connector. These steps are vital for the success of your integration.

Configuring Akeneo PIM Catalog Structure

When integrating Akeneo PIM with your existing Adobe Commerce catalog, careful consideration of your catalog's structure is essential. The modelization of your Akeneo PIM catalog should align with your current catalog structure in Adobe Commerce. If the data structure you establish in Akeneo PIM significantly deviates from your Adobe Commerce setup, it can lead to challenges during data transfers and compatibility issues due to the inherent disparities between the two systems.

Conversely, deploying an Akeneo PIM instance presents an opportunity to reassess your catalog structure and enrichment workflows. However, you should be mindful that any structural changes made may impact your established Adobe Commerce catalog structure and synchronization processes with the connector.

In such cases, it may be necessary to conduct some cleaning or restructuring within Adobe Commerce before implementing the connector. These proactive steps are critical to ensuring a smooth and successful integration that maintains consistency and data integrity between Akeneo PIM and Adobe Commerce.

Professional Services

Our dedicated Professional Services team is here to assist you and your integration partner (integator) in the critical process of PIM modelization. We provide expert guidance and support to ensure your product information management (PIM) model is structured optimally for your business needs. Our team works closely with you to create a customized PIM model that aligns with your unique requirements, helping you maximize the benefits of your PIM implementation. Please reach out to your Customer Success Manager for more information.

 

 

Initializing your Catalog Data in Akeneo PIM 

Following the setup of your new Akeneo PIM instance, the next crucial step is to import your current catalog data. This data import can originate from either your existing Adobe Commerce or your Enterprise Resource Planning (ERP) system.

Please be aware that this process is highly specific and contingent upon the choices you've made regarding your Akeneo PIM catalog structure and internal organization.

It's important to note that the Akeneo Connector for Adobe Commerce is primarily designed to synchronize data from Akeneo to Adobe Commerce. It does not facilitate the transfer of data from Adobe Commerce to Akeneo PIM. This transfer must be independently executed, taking into account your specific catalog structure and requirements.

Before proceeding with the installation of the Akeneo Connector for Adobe Commerce on your existing Adobe Commerce platform, please consider the following.

You may be in the process of setting up a new Akeneo PIM instance and intend to connect it to your pre-existing Adobe Commerce environment. 

The installation and configuration of the Akeneo Connector for Adobe Commerce represent just one step in your overall migration process. 

When you're installing the Akeneo Connector for Adobe Commerce on an existing Adobe Commerce instance that already contains entities like products or attributes, you need to consider the differences in catalog and entity structures between Akeneo PIM and Adobe Commerce.

The connector employs a custom table (akeneo_connector_entities) to establish and store the relationships between Akeneo PIM entities and Adobe Commerce entities. These relationships are established when entities are imported using the connector.

However, if you're installing the connector on an existing Adobe Commerce instance, the relations in the Akeneo Connector's custom table may not be present. In such cases, the connector may not automatically know which Akeneo PIM entity corresponds to which Adobe Commerce entity.

Starting from version 100.3.4 of the Akeneo Connector for Adobe Commerce, it's now possible to automatically map specific entity types from Akeneo PIM to existing entities in Adobe Commerce during the initial import. The supported entity types include Attributes, Options, and Products.

Prior to synchronization in an existing Adobe Commerce environment, it's essential to back up your data and conduct testing in a non-production setting.

 

Here's a breakdown of each entity type and general recommendations to ensure a successful connection between your Akeneo PIM and your existing Adobe Commerce instance using the Akeneo Connector for Adobe Commerce.

Categories

Since the 104.1.0 version of the Connector it is possible to map the pre-existing Categories.

I have an e-commerce with existing categories and an Akeneo PIM without categories

In this case, you need to export your category tree to the PIM. This allows the link of website categories to PIM categories. Next, when you will import categories from Akeneo to the Website, the category will be updated and not duplicated.

This action must be performed only upon initialization. Categories should only be updated on the PIM afterwards.

  1. Access the Akeneo Connector admin configuration by navigating to "Store > Configuration > Catalog > Akeneo Connector."
  2. Within the configuration settings, locate and click on the "General" tab.
  3. In the "General" tab, find the option labeled "Export Categories."
  4. Enable or select the "Export Categories" option.
  5. Once enabled, the system will automatically generate a CSV file containing your category tree, which is ready for import into your Akeneo PIM instance.

I have an e-commerce with existing categories and an Akeneo PIM with existing categories

In this case, you need to link e-commerce category tree to the Akeneo category tree. The only way to link entities, is to match the category structure and labels. The categories must have the same structure and the same label in e-commerce and PIM.

  1. Access the Akeneo Connector admin configuration by navigating to "Store > Configuration > Catalog > Akeneo Connector."
  2. Within the configuration settings, locate the "Category" section.
  3. In the "Category" section, find the field labeled "Match existing categories in Akeneo."
  4. Set the option to "Yes" to indicate that you want to match existing categories in Akeneo.
  5. Once you've selected "Yes," proceed to launch the category import process. This action will link the existing categories between your e-commerce store and Akeneo PIM, ensuring a seamless connection.

When this option is enabled, no category is created. The connector only try to make the link between categories. If a category exists in the PIM and not in e-commerce, the category will not be created in e-commerce. If a category exists in e-commerce and not in the PIM, the category will not be created in e-commerce.

Ecommerce Akeneo Link
Master Catalog > Clothes > T-Shirts Master Catalog > Clothes > T-Shirts
Master Catalog > Clothes > T-Shirts Master Catalog > Clothes > T-Shirt
Master Catalog > Apparel > T-Shirts Master Catalog > Clothes > T-Shirts
 

If the category label is different between the PIM and the Website, you need to update the label.

This action must be performed only upon initialization. Categories should only be updated on the PIM afterwards.

Once the link is done, you need to disabled the “Match existing categories in Akeneo” option.

 
 
 

Families

At this point, it is not possible to link existing families from Adobe Commerce to Akeneo PIM families as there is no code inside Adobe Commerce to match with the Akeneo PIM family code.

Our recommendation is to import new families from Akeneo PIM, let the product job link your products to the new families, and delete the old families.

A family (attribute set) inside Adobe Commerce can be deleted only if no products are associated to it.

 
 
 

Attributes

When importing for the first time to an existing Adobe Commerce instance, attributes with the same code inside Akeneo PIM and Adobe Commerce will be automatically linked in the Akeneo Connector entity tables.

Make sure that the attribute type in Adobe Commerce matches your attribute type in Akeneo PIM.

If not, a warning message will appear and the attribute will be skipped.

Consult the Akeneo Connector default attribute type mapping for more information: Attribute types

 
 
 

Attribute options

When importing for the first time to an existing Adobe Commerce instance, attribute options are automatically linked to your existing Adobe Commerce attribute options based on their "Admin label".

If an option in Adobe Commerce for a specific attribute has an "Admin Label" matching the Akeneo PIM option label in your Adobe Commerce admin locale, the connector will setup the link during the first import.

Since the 101.6.0 version of the Akeneo Connector for Adobe Commerce, you can set Akeneo attribute option code as Admin label in Adobe Commerce. If you do so, the mapping will be based on the code of your attribute options in Akeneo corresponding to your existing Adobe Commerce attribute option Admin label. For more information, please consult the associated documentation: Configure Attribute Options

Since the version 103.3.0 of the Akeneo Connector for Adobe Commerce, if a select / multi-select / reference entity select / reference entity multi-select attribute is mapped from the "Attribute Mapping" configuration to an existing Adobe Commerce attribute with the same type, the options from the Akeneo attribute will automatically be created and mapped in the corresponding Adobe Commerce attribute.

To know more about the attribute type mapping from Akeneo to Adobe Commerce, please consult the Attribute type documentation page.

 
 
 

Product models and family variants

Product model and family variant jobs has been removed since the 101.0.0 version of the Akeneo Connector for Adobe Commerce and merged into the Product job

 

Product models and family variants data is stored into internal Akeneo Connector tables and will be used during the Product import job process.

This data doesn't need any link to Adobe Commerce entities so you will just have to launch the corresponding jobs to fetch the data from Akeneo PIM before launching the product job.

 
 

Products

Products are automatically linked from your existing Adobe Commerce product SKU and the Akeneo PIM product identifier. It includes simple and configurable products in Adobe Commerce (product models and variant products in Akeneo PIM).

The data coming from Akeneo PIM will replace the existing data inside your Adobe Commerce products.

 
 

Synchronizing your Akeneo PIM data to your Adobe Commerce for the first time

With your Akeneo PIM instance prepared, the connector successfully installed and configured within your Adobe Commerce environment, you are now ready to execute your first synchronization between these two systems.

However, it's essential to keep in mind that this kind of integration entails rigorous testing and comprehensive data analysis. These post-synchronization activities are crucial to ensure there are no misconfigurations or unintended side effects that could impact the smooth operation of your data transfer processes. Thorough testing and ongoing analysis are key to maintaining the integrity and efficiency of your data connection.

A production environment should not be used to test the first synchronization between Akeneo PIM and Adobe Commerce.