Installation

Summary

Introduction

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

To ensure a successful installation of the connector, we strongly recommend enlisting the expertise of a technical resource with a proven track record of SAP Commerce Cloud skills and Akeneo PIM knowledge. This individual or team should have a demonstrated proficiency in both SAP Commerce Could, Integration Suite and BTP and the specifics of the integration to carry out the installation effectively. Their experience and knowledge will be instrumental in setting up the connector correctly and maintaining its optimal performance. If you need assistance in finding the right partner, please reach out to your Customer Success Manager (CSM) for further details and assistance.

Please make sure to review the what you need to know section including the compatibility page before before getting the integration.

Getting the connector

To acquire the integration, 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 your Akeneo Partner Portal and assist you in leveraging Akeneo Support for your enterprise needs.

Project management pre-requisite on the portal

The Akeneo integration app for SAP Commerce access is hosted on the Project Console of the Akeneo portal as mentioned above. Please make sure you meet the following project management prerequisites to be able to install the integration:

Ensure you have access to the connector within the Akeneo Portal
Create a developer profile within your organization, who will be responsible for the installation. Grant this developer access to the Project Console.
Download the integration. You are all set.
You will be able to retrieve the new versions through this portal. Please subscribe to the appstore to receive mail on updates.

Installing the connector

Pre-requisites

You have downloaded the connector from your Akeneo portal (see above)
You have access to a SAP Commerce Cloud instance
You have SAP BTP and Integration Suite instances with necessary entitlements and user roles
You have whitelisted the Integration suite server IP address in Commerce Cloud. Please refer to the IP address list

Configuring your PIM API and retrieving the GraphQL Service URL

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

Key Information you will need for integration configuration (security material and global configuration):

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

Those are the only steps you will need to configure in the PIM.

The GraphQL Service URL will need to be configured in the security details of the Integration Suite and is https://graphql.sdk.akeneo.cloud

Downloading the connector code in SAP integration Suite

In your integration suite environment:

Go into Design
Integrations and APIs
Click Import
Select the connector app zip file from the file system. You should be able to see the iFlow package named "Akeneo Integration with SAP Commerce Cloud". This package contains all the Integration artifacts for the connector app.

Visual helper - Finding the Akeneo package in the Integration Suite

Visual helper - the Akeneo integration artifacts

Installing the integration app on SAP Commerce Cloud environment

Pre-requisite

Install the Integration API in SAP Commerce Cloud: Installing the Integration Extensions
Manifest Setup. Make sure to have the following in one public endpoint (e.g.: API)
- odata2webservices
- authorizationserver

Install the extention in your SAP Commerce Cloud environment

Copy the "akeneosapconnector" folder into your SAP CC "custom" folder
Modify impex with your custom catalog
- Go to "akeneosapconnector/resources/impex/akeneo-classification.impex"
- Update the impex with your own catalog details
  - Product Catalog Name
  - Classification Catalog Name
  - Classification Catalog Version
- Note: This impex can only be run during system update to avoid errors due to catalogs not present during initialization. The ClassificationAttributeUnit, ClassificationClass,ClassificationAttribute, ClassAttributeAssignment will be handled by the family import.
Build and Update your system

CCv2 Portal

CCv2 is the cloud environment portal where access and deployment of SAP Commerce Cloud is controlled.

Public Endpoint Setup

If encountering Error 429: Too many requests, kindly change the WAF Rate Limit in your endpoint. See steps below:

Go to CCv2 Portal
Select desired environment and then select the public endpoint
Find Web Application Firewall and change Rate Limit
It is suggested to have lower rate limit to cater many calls in OData API: configure Higher threshold of request and lower cooldown time limit to cater many calls in OData API.
See documentation here: Configuration of WAF at an Endpoint Level

Activate the connectivity: Security material configuration and URL in the Integration Suite

The main installation steps are done and the connectivity must now be set up. To do so you must:

Configure the security materials
Configure the Global configuration of the integration

Security materials

In the Integration Suite, go to

Monitor
Integrations and APIs
Security Material

Then in security materials, you must create the user and client credentials. There will be a total of 4 security materials to create.

User credentials: PIM, SAPCC

Two security materials to create

Parameters	Content
Name	Text field, suggested name “Akeneo_PIM” and “SAP_CC”
Description
Type	Single Select, select “User Credential”
Password
Repeat password

OAuth2 client credentials: GraphQL, SAP_CC

Two security materials to create

Parameters	Content
Name	Text field, suggested name “GraphQL", “SAP_CC”
Token Service URL	Type the URL “https://graphql.sdk.akeneo.cloud ” or the SAPCC Service URL
Client ID	Client ID of the PIM
Client Secret	Client Secret of the PIM
Client Authentification	Single select, select “Send as Request Header”
Content type	Single select, select “application/json”

Let empty the scope, resource and audience fields

Setting up on a pre-existing SAP Commerce Cloud

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 SAP Commerce Cloud 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 SAP Commerce Cloud. If the data structure you establish in Akeneo PIM significantly deviates from your SAP Commerce Cloud 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 SAP Commerce Cloud catalog structure and synchronization processes with the connector.

In such cases, it may be necessary to conduct some cleaning or restructuring within SAP Commerce Cloud 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 SAP Commerce Cloud.

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 mostly originates from either your existing SAP Commerce Cloud 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 SAP Commerce Cloud is primarily designed to synchronize data from Akeneo to SAP Commerce Cloud. It does not facilitate the transfer of data from SAP Commerce Cloud 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 SAP Commerce Cloud on your existing SAP Commerce Cloud 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 SAP Commerce Cloud environment.

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

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

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

The connector may not automatically know which Akeneo PIM entity corresponds to which SAP CC entity. This is especially if there are types in SAP CC that are not available OOTB. In this case, you may modify the message mappings to make sure that each PIM attribute is imported correctly in the type and format that is acceptable in SAP CC. Please refer to this documentation for sample modification on the message mappings.

Depending on how the pre-existing SAP CC is already structured, you may need to make necessary adjustments to the Akeneo Connector to SAP Commerce Cloud so that there would be no duplicate records created when import is executed. With that, you also need to be familiar on the naming conventions that are being followed in your pre-existing SAP CC environment, especially for different type identifiers. Listed below are the naming conventions that the connector is following when importing new/existing objects to SAP CC. If there is any difference from the naming convention that is already being done in the pre-existing CC, you may navigate to the corresponding connector artifacts listed and update the naming as needed.

SAP CC Type	SAP CC Identifier	Connector Naming Convention	Connector Artifacts / Files to Modify
Classification Unit	Code	<AKN_Unit_Code>	Classification Unit Mapping
Classification Class	Code	<AKN_Family_Code>	Classification Class Mapping
Classification Attribute	Code	<AKN_Attribute_Code>	Classification Attribute Mapping
Category	Code	<AKN_Category_Code>	Category Mapping
Variant Category	Code	<AKN_Product_VariationAxes_Code>	Akeneo scripts - product_models_variation_axes.groovy
Variant Value Category	Code	Default Attribute: <AKN_Product_VariationAxes_Code>_<AKN_Product_Attribute_Value_Data> Reference Entity: <AKN_Product_VariationAxes_Code>_<AKN _ReferenceEntity_Code> Metric: <AKN_Product_VariationAxes_Code>_<AKN_MetricAttribute_Amount><AKN_MetricAttribute_Unit>	Akeneo scripts - product_variant_value_categories.groovy
Price Class	Code	Product Model: <AKN_Price_Attribute_Code><AKN_ProductModel_Code> Variant Product: <AKN_Price_Attribute_Code><AKN_Product_UUID>	Price Classes Mapping
Product Media	Code	Product Model: <AKN_ProductModel_Code>_<AKN_Attribute_Code>_<AKN_Asset_Code>_<AKN_AssetMediaLink_Code> Variant Product: <AKN_Product_UUID>_<AKN_Attribute_Code>_<AKN_Asset_Code>_<AKN_AssetMediaLink_Code>	Akeneo scripts - product_media_mapping.groovy
Product Media Container	Qualifier	Product Model: <AKN_ProductModel_Code>_<AKN_Attribute_Code> Variant Product: <AKN_Product_UUID>_<AKN_Attribute_Code>	Akeneo scripts - product_media_container_mapping.groovy
Product	Code	Product Model: <AKN_ProductModel_Code> Variant Product: <AKN_Product_UUID>	Product Mapping Akeneo scripts - product_features_classification_attribute_mapping.groovy and product_reference_mapping.groovy Optional: All other artifacts above where product model code or product UUID were mentioned

#Synchronizing your Akeneo PIM data to your SAP Commerce Cloud for the first time

With your Akeneo PIM instance prepared, the connector successfully installed and configured within your SAP Commerce Cloud 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 SAP Commerce Cloud.

Akeneo Help Center