commercetools extension setup and installation instructions

In order to set up and install the commercetools extension, you need to make sure you have your prerequisites in place, add structured metadata in Cloudinary, and install your preferred microservice.

Prerequisites

Make sure you have a Cloudinary account. You can start by signing up for a Free plan. When your requirements grow, you can upgrade to a plan that best fits your needs.

Make sure that you have the following information readily available. When executing the deployment commands, e.g., sam deploy --guided, you’ll be asked for these configurations:

Parameter	Example	Description
CloudName	abcdef123	Your Cloudinary cloud name.
CloudApiKey	123456789	Your Cloudinary API key.
CloudApiSecret	ABCdef123	Your Cloudinary API secret.
PropertySku	commercetools_sku	The Cloudinary structured metadata field that contains the SKU of the Product it’s associated with.
PropertyPublish	commercetools_publish	The Cloudinary structured metadata field that triggers an action in your storefront when changed.
AuthUrl	https://auth.example.commercetools.com	The commercetools Auth URL of your project.
ClientId	https://api.example.commercetools.com	The client ID of your commercetools project.
ApiUrl	AbC-dEf-123	The commercetools API URL of your project.
ProjectKey	abc_123	The commercetools project key.
CtApiSecret	ABCdef123	The API secret for the provided commercetools API key.

Add metadata in Cloudinary

Create the following structured metadata fields in Cloudinary (see Adding structured metadata fields for instructions):

Required structured metadata fields

You can use any name you'd like for your structured metadata fields. However, you must use the text specified in the table as the field's external ID.

External ID	Type	Description
commercetools_sku	Text	Specifies the SKU of the Product that the Cloudinary asset is linked to. Note: An asset without a value for this field isn't linked to a Product.
commercetools_publish	Single-selection list (cld_ct_publish, cld_ct_draft, cld_ct_unpublish)	Changing the value for this field triggers one of the following actions: - cld_ct_publish: Adds the asset to the published ProductVariant. - cld_ct_draft: Adds the asset to the ProductVariantDraft. - cld_ct_unpublish: Removes the asset from the published ProductVariant.

Optional metadata fields

You can optionally create other fields in Cloudinary that will update commercetools Product Assets Attributes when you publish the asset. Just make sure the external ID of the field in Cloudinary matches the name of the Attribute used in commercetools.

Optional field for positioning assets on your PDP

You can control the position of the commercetools Product Asset on the PDP page via Cloudinary. Create a field in Cloudinary with a specific external_id, for example "sortNumber", and make sure you use the same name in your commercetools configuration for this parameter when deploying the website or app.

The commercetools Product Asset’s position on the PDP is updated according to the new value in the "sortNumber" field, at the time that the asset is published.

Install a microservice

The serverless microservice that drives the integration of Cloudinary assets in your commercetools instance can be hosted on one of the following widely-used cloud providers: Amazon AWS, Google Cloud Platform, or Microsoft Azure.

Amazon AWS

The integration is built on top of AWS Cloudformation using the following services:

• ECR to host the used Lambda docker image
• API Gateway for the webhook entrypoint
• AWS Lambda to process the notification
• Secrets manager for API key management

Prerequisites

• AWS & SAM CLI installed
• An account with permissions to create and manage AWS Resources
• Docker CLI to build your Lambda container image

Installation

The GitHub repository includes an automated installation script to create the Secrets and a SAM template with:

• API Gateway with SQS integration
• AWS Lambda with an SQS trigger

1. Create secret manager secrets, store the ARN of your secrets to be used later during deployment of your stack:

   Cloudinary API secret:

   commercetools API secret:

2. Build SAM template:

3. Deploy SAM template:

4. When you finish your installation, you'll receive a webhook URL as output. To utilize it:

   1. Navigate to the the Webhook Notifications page of the Console Settings:
   2. Click Add Notification URL.
   3. Paste the webhook URL into the Notification URL field for the newly added webhook.
   4. Keep Default - All notifications as the Notification Type.

Google Cloud Platform

The GCP integration uses the following resources:

• API Gateway for the webhook entrypoint with an OpenAPI spec
• Cloud Run to handle incoming notifications by posting it to a PUB/SUB
• PUB/SUB topic for all incoming Cloudinary notifications
• Subscription on the PUB/SUB to pass all messages to Cloud Run
• Cloud Run to process the notifications asynchronously
  • Failed processes are moved to $Topic-dead-letter
• Secrets to store API keys

Installation

The GitHub repository includes detailed installation steps and command line scripts to install the required resources.

When you finish your installation, you'll receive a webhook URL as output. To utilize it:

1. Navigate to the the Webhook Notifications page of the Console Settings:
2. Click Add Notification URL.
3. Paste the webhook URL into the Notification URL field for the newly added webhook.
4. Keep Default - All notifications as the Notification Type.

Microsoft Azure

The Azure integration uses the following resources in a Bicep template:

• Storage account
• App service plan
• App insights
• Service Bus + Queue
• Function
• KeyVault
• API management

Installation

The GitHub repository includes detailed installation steps and command line scripts to install the required resources.

The easiest way for you to set up the Azure integration is by using the provided Powershell script.

1. Edit the settings JSON file, found at /azure/settings/commercetools.json and fill in the following values:

   • Subscription: The name of the Azure Subscription where resources will be deployed.
   • ResourceGroup: The name of the Azure ResourceGroup where resources will be deployed.
   • KeyVaultName: The desired name for the KeyVault.
   • ApplicationId: The desired name for the application (resources will be named, for example, apim-<applicationId>, func-<applicationId>, etc.)

2. Open Powershell with the Azure CLI installed:

   • Go to /azure/scripts
   • Run .\deploy-initial.ps1

3. When you finish your installation, you'll receive a webhook URL as output. To utilize it:

   1. Navigate to the the Webhook Notifications page of the Console Settings:
   2. Click Add Notification URL.
   3. Paste the webhook URL into the Notification URL field for the newly added webhook.
   4. Keep Default - All notifications as the Notification Type.