Introduction

To ensure a successful installation of the connector, we strongly recommend enlisting the expertise of a technical resource with a proven track record of SFCC B2C skills and Akeneo PIM knowledge. This individual or team should have a demonstrated proficiency in both SFCC 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.

Before getting access to the SFCC connector, please check the what you need to know before using the connector section.

Getting the connector

Akeneo Connector for SFCC (Enterprise Edition) is compatible with Akeneo PIM Enterprise Edition (please refer to the compatibility and pre-requisite article for more information). 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.

Downloading the code from the Portal

the Akeneo Connector for SFCC B2C code access is hosted on the Project Console of the Akeneo portal. Before you can begin the installation, 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.

Once you clicked, you will have to select the archive version that you want to install.

Configuring your PIM API in Akeneo 

Acquire an access token

If you have never used the Akeneo API, please follow the below instruction to acquire an access token.

Generate the client ID and secret

Before setting up the Akeneo Connector for SFCC, make sure the prerequisites are covered. For the API configuration, you first need to generate a "client ID" and "secret" couple in the PIM to enable the API connection.

Please refer to our specific documentation to do so.

You will be given the following items:

1. Your PIM URL (ex: https://mypim.cloud.akeneo.com)
2. Your PIM API Client ID and Secret
3. Your PIM user who will be dedicated to the use of the API (Username and Password). Make sure you save them as you'll need them later.

Exclude attribute groups from the import process

To improve performance and reduce the number of data imported, you can exclude attribute groups from the import . To do so, please configure  the Connection permission. 

Once you have created the permission group, add it to the attribute in the permission section for every single attribute group you want to import.

Installing the connector on SFCC B2C

Upload the cartridge on SFCC

WebDAV

Upload cartridges to WebDAV using any method of your choice.

 

 

Set up the cartridge path

1. Go to Business Manager Menu > Administration -> Sites -> Manage Sites.
2. Click on "Business Manager" in the "Manage the Business Manager site" text.
3. Prepend "bm_akeneo:" to the "Cartridges" field.
4. Click on Apply button.

Cartridge path screnn

 

 

Metadata Import

For the Akeneo Connector for SFCC to work, the following object structures (metadata) need to be imported and configured in the Business manager.

Follow the steps below:

1. In the cartridge bundle find metadata/simple-akeneo-workflow_site-import and compress it to generate the simple-akeneo-workflow_site-import.zip file.
2. Go to the Business Manager Menu: Administration > Site Development : Site Import & Export
3. Under Import : Upload archive: Make sure that the radio button with label Local is enabled (otherwise click on the radio button to enable it).
4. Click on the Choose File input field, select the simple-akeneo-workflow_site-import.zip file from the open dialog box and click on Upload.

1. After finishing the upload, from the Archives list click on the radio button corresponding to simple-akeneo-workflow_site-import.zip and click on Import.
2. Click on the OK button of the confirmation box asking "Are you sure that you want to import the selected archive?"

Log API communication (debug mode)

Go to Business Manager Menu: Administration > Operations : Services > AkeneoGetGeneral

Tick the Communication Log Enabled checkbox if you want API communication to be logged.

Repeat the same for AkeneoGetToken.

Add the cartridge to your sites

1. Go to Business Manager Menu: Administration > Sites : Manage Sites.
2. Select your site.
3. Click on the Settings tab.
4. Append ":bc_akeneo" (or bm_akeneo depending on the cartridge version) to the Cartridges field.
5. Click on Apply.
6. Repeat steps 2. to 5. for all sites including the Business Manager one.

Fill in all Akeneo configuration in Site Preferences.

Schedule job as needed, and start the synchronization with the Akeneo instance! 😉

OCAPI (Open Commerce API) Configuration 

Akeneo SFCC Connector uses OCAPI (Open Commerce API) calls for its operations. For the connector to function properly, OCAPI settings should be adjusted on BM by following these instructions. 

1. Go to Administration > Site Development > Open Commerce API Settings 

API Settings visual

 

 

• Select the type as Data and context as Global (organization-wide). Locate the text file Akeneo-OCAPI-Data-Config.txt in the documentation folder in the Akeneo SFCC Connector cartridge package. This file contains the OCAPI Data configuration for Akeneo SFCC Connector. Copy the configuration from the Akeneo-OCAPI-Data-Config.txt file and paste it into the Open Commerce API Settings on BM (If you plan to keep your existing OCAPI configuration, you may want to add OCAPI configuration of Akeneo SFCC Connector to the end of your existing OCAPI configuration instead of completely replacing it with Akeneo SFCC Connector configuration). Replace the “PLACEHOLDER_OCAPI_CLIENT_ID” with your OCAPI client ID. Click on Save button. 

Custom Object Usage

Custom Object: AkeneoTopLevelCategoriesCode: This custom object is used to store category codes which will be retrieved from Akeneo.

Custom Object: AkeneoRunTime: This custom object is used to store the job executed time which will be used in differential job execution to retrieve only updated products from Akeneo.

Custom Object: AkeneoToken: This custom object is used to store the token retrieved from Akeneo for authorization.

External Interfaces

Akeneo provides a REST API for accessing to instance’s data.

More information here: https://api.akeneo.com/api-reference-index.html

To begin the integration process and gain authorization to retrieve data from their API, we must first acquire an access token.

Firewall Requirements

There is one firewall requirement in Akeneo’s instance. Merchant must provide their outgoing IP address to Akeneo to configure in API environment to whitelist the SFCC environment.

Establish the connection within the connector configuration panel

In the connector configuration page, fill in the parameters below with the PIM information collected above:

Installing with a pre-existing B2C Commerce

Overview

It is feasible to manage products in both Akeneo and legacy products within Salesforce Commerce Cloud (SFCC) simultaneously.

This section outlines the features of the Akeneo connector and its integration with an existing catalog.

Site preferences

This section outlines the settings of the Akeneo connector and their interaction with Salesforce Commerce Cloud (SFCC) catalogs that may cause an impact when non-managed products and categories are mixed with Akeneo products and catalogs.

SFCC Master Catalog ID

This setting is located in the General tab of the connector's configuration dashboard. This setting indicates the ID of the master catalog to be used by the connector. As SFCC supports multiple master catalogs, you can assign a distinct master catalog ID to the connector, allowing for the separation of manually configured products from those managed by the PIM. 

A key limitation of the platform to consider is that IDs for an SFCC object type must be globally unique across the entire instance. Consequently, only one product can have the ID "Product1" across all catalogs. If a product with this ID already exists in one catalog, any attempt to import it into another catalog will be disregarded. This becomes particularly relevant if a gradual migration of manually configured products to the PIM is desired, and separate catalogs are being utilized.

Product Status Sync

This setting is located in the General tab of the connector's configuration dashboard.

This setting determines if the PIM product enable status will be used as the online flag value in the imported product.

Sync Empty Product Values

This setting can be found in the General tab of the connector's configuration dashboard.

This setting specifies whether values cleared in the PIM will also be cleared during

the SFCC product import.

This setting is important due to the behavior of the SFCC platform. When importing in merge mode, any absent attributes are treated as unchanged.

Therefore, removing an attribute value from the PIM will not affect the SFCC product unless this setting is enabled.

Akeneo Main Category

This setting can be found in the General tab of the connector's configuration dashboard. This setting specifies which of the PIM's category trees will be selected for import into the SFCC storefront catalog.

Top Level Category for Storefront Catalog

This setting can be found in the General tab of the connector's configuration dashboard. This setting identifies which of the PIM's categories from the selected tree will be regarded as equivalent to the root category. Any category with this category ID as its parent will be reparented as a root category.

PIM Categories Sync

This setting can be found in the General tab of the connector's configuration dashboard. This setting specifies, at the site level, whether categories and category assignments to PIM categories will be imported into Salesforce Commerce Cloud SFCC) from Akeneo.

SFCC Categories Sync

This setting can be found in the General tab of the connector's configuration dashboard.

This setting determines, at the site level, whether Akeneo products can be assigned to Salesforce Commerce Cloud (SFCC) categories. If set to "disabled," it

will unassign PIM products from SFCC categories.

Online Categories Sync

This setting can be found in the General tab of the connector's configuration dashboard. This setting controls the online status flag of imported Akeneo categories.

Setting this to "enabled" will make all imported categories online. 

Choosing "disabled" will set all imported categories to offline, while selecting “unassigned”will preserve the current state of the online flag. Unlike virtually all enable/disable toggles in the configuration dashboard that operate on binary logic, this setting employs ternary logic.

Product Primary Flag Sync

This setting can be found in the General tab of the connector's configuration dashboard. The concept of a primary category is a feature unique to Salesforce Commerce Cloud (SFCC) that is not natively available in the PIM. This setting determines whether a product imported from Akeneo will have a primary flag set. The primary category is designated as the first category received from the Akeneo PIM API.

Product Attribute Mapping

This setting can be found in the Product Mapping tab of the connector's configuration dashboard.

The connector includes three types of mappings.

• System Attributes Mapping: This mapping is utilized to align Akeneo attributes with Salesforce Commerce Cloud (SFCC) system attributes. It focuses solely on value mapping for products, without managing the attributes themselves.
• Renaming Attribute Mapping: This mapping is used to align Akeneo attributes with Salesforce Commerce Cloud (SFCC) custom attributes. It allows for custom names to be assigned to attributes, preventing them from being prefixed with “Akeneo.”
  • Note that, in addition to value mapping, any attribute included in this list will have its definition managed by Akeneo.
• Type Transformation Attribute Mapping: This mapping is utilized to align Akeneo attributes with Salesforce Commerce Cloud (SFCC) custom attributes. It focuses solely on value mapping for products, without managing the attributes themselves.

Akeneo Image View Types

This setting can be found in the Images & Assets tab of the connector's configuration dashboard. This configuration controls the Akeneo master catalog image view types. If the master catalog contains non-imported products, it ensures that the existing configurations are not lost.

Conclusions

Unmigrated products scenario 

If there are products in the catalog that have not been migrated and there is no intention to migrate them, the optimal approach is to utilize a separate master catalog. The platform supports the coexistence of multiple master catalogs, allowing them to be used on the same site.

If there is a desire to gradually migrate the products over time while preserving the product IDs, it is preferable to use the same catalog as the existing products. As long as the cartridge is configured to use SKUs instead of UUIDs, and the Akeneo product code matches the ID of the old product in Salesforce Commerce Cloud (SFCC), the products will be managed by the Akeneo PIM.

Regardless of the approach employed, the cartridge will not remove existing products or alter them unless they are added to the PIM. The cartridge does not perform migration of existing products to the PIM or in any way mark the existing products as not originating from the PIM.

Migration must be conducted by the merchant using the PIM dashboard, either manually or through some form of import. However, this process is outside the scope of the connector.

When using separate master catalogs and migration is desired, it is necessary to remove products from the unmigrated catalogs before importing the migrated products, as in SFCC, product IDs are globally unique across all catalogs.

Unmigrated category scenario

Unlike the case for products, where the SFCC platform allows for multiple master catalogs, the SFCC platform permits only one storefront catalog. Consequently, this catalog will necessarily contain a mixture of migrated and unmigrated categories.

While managing the catalog in the PIM is possible, it is not a requirement. You can fully manage the storefront catalog in SFCC; however, this approach necessitates manually managing the catalog assignments in SFCC as well.

The connector is designed to allow migrated and unmigrated categories to coexist within the same storefront catalog; however, certain caveats apply. The main items that need to be considered are the following:

• If the SFCC Categories Sync preference is disabled, products managed by the PIM will be unassigned from SFCC categories.
• Catalog-level refinements are saved and re-added to the storefront catalog, whereas category-level refinements are not.
• Category custom attributes are not configurable in the PIM, and the connector will only set the `showInMenu` custom attribute.
• The Online Categories Sync preference sets both the online flag and the `showInMenu` custom attribute of the category.

It is possible to suppress the importing of categories from the PIM while still utilizing the PIM for category assignments by disabling the Categories flag on the `custom.Akeneo.CatalogImport` job step.

Handling of master variation products

Existing unmigrated master variation products will not be affected by product imports from the PIM. When migrating master variation products to the PIM, if maintaining the product IDs is considered necessary, care must be taken to ensure that the code of the master and its variations matches those in SFCC and the cartridge is configured to use SKUs instead of UUIDs.

Handling of product bundles and product sets

The SFCC platform supports the concept of product bundles and product sets, whereas the Akeneo PIM does not natively support these concepts. The connector leverages functionality present in the PIM, specifically product associations, to recreate the relationship mechanism found in SFCC product bundles and sets.

The connector defines site preferences accessible from the connector configuration dashboard under the Product Associations tab. In the Product Set and Product Bundle subsections, configurations for family are available.These preferences are used to specify which PIM product families should be treated as bundles and sets, respectively, when imported into SFCC. Only the products intended to be imported as bundles or sets should be included in the corresponding families; their subproducts must not be included.

In the Product Set and Product Bundle subsections, configurations for associations are available. These preferences are used to specify which PIM product associations should be treated as bundle and set relationships, respectively, when imported into SFCC. Existing unmigrated bundles and sets will not be affected by this functionality. Migrating bundles and sets should follow the same rules as the migration of simple products.

Handling of images and static media

One area where complications can arise when mixing migrated and unmigrated products is in the handling of images. 

The connector will override settings regarding view type definitions on the master catalog it imports into. As such, incomplete or incorrect configuration of the Akeneo Image View Types preference can result in data loss for unmigrated products. The `Remove Downloaded Assets On Full Import` and Remove Downloaded Media On Full Import`options from the Image Assets tab of the configuration module will result in image loss for unmigrated products.

To avoid these pitfalls, it is preferable to utilize a separate master product catalog. 

Jobs configuration information

The Akeneo connector for SFCC B2C defines several import jobs.

1.0 - Akeneo-Full-Import – The job will perform a full import of the PIM data based on confirmation. The import includes attributes metadata, catalog, pricebook,

reference entity, and images and media imports.

2.0 - Akeneo-Scheduled-Differential-Import: This job will perform a delta import of the PIM data based on confirmation and the last import date saved in custom objects. The import includes all the elements of the full import job. Note that attributes metadata is always imported fully, even in the differential import job.

The 3.x jobs that come with Akeneo allow individual items to be imported. All of the 3.x job steps are present in the 1.0 and 2.0 jobs.

The job steps present in the Akeneo jobs are as follows:

`Custom.Akeneo.AttributeImport` - This step is present in the 1.0, 2.0, and 3.1 jobs and is responsible for importing system object type changes from Akeneo to SFCC.

`Custom.Akeneo.MediaAssetImport` - This step is present in the 1.0, 2.0, and 3.2 jobs and is responsible for importing image and media files into SFCC.

`Custom.Akeneo.EntityImport` - This step is present in the 1.0, 2.0, and 3.3 jobs and is responsible for importing reference entities into the SFCC library. The import of reference entities does not affect existing content assets, folders, or PD pages, as all Akeneo PIM data is self-contained within its own folder.

`Custom.Akeneo.PricebookImport` - This step is present in the 1.0, 2.0, and 3.4 jobs and is responsible for importing price books into the SFCC . The import utilizes its own price books and does not alter the existing price books in SFCC.

Custom.Akeneo.CatalogImport - This step is present in the 1.0, 2.0, and 3.5 jobs and is responsible for importing catalog data into the SFCC.

The import step has several settings unique to it, allowing for customization and control over the import process.

Disabling the flags will suppress the generation of the corresponding part of the catalog import.

A common setting for all Akeneo job types is the enable flag, which controls whether the step is active or not.

Another common setting for all Akeneo job types is the Log Level, which determines the type of logs the step will emit. The levels include Error, Warning, and Info. Lower log levels include the higher ones, meaning Info includes Warning and Error, and Warning includes Error.

All import steps, except for `Custom.Akeneo.AttributeImport`, include an Import Type setting that determines the mode of the import, either Full or Differential.

Error handling and retry

All jobs will emit logs based on the configured log level and will terminate with an error if a fatal issue is encountered. It is strongly recommended that you configure notifications on all jobs that you will be using.In case of a connection issue with the PIM, the connector has an automatic retry mechanism for retrieving data.