Salesforce Commerce Cloud B2C Commerce Cartridge for SFRA

This is the recommended cartridge if you already have a storefront on SFRA, or are new to Salesforce Commerce Cloud (SFRA is the more recent architecture).

Set up the SFRA B2C Commerce cartridge

Download the B2C Commerce cartridge

You can download the certified SFRA B2C Commerce cartridge from the Cloudinary page on the SFCC Link Marketplace (requires SFCC login). You can also get the most recent release from Cloudinary's GitHub repo.

Install the cartridge on the sandbox

1. In the top level folder of the downloaded package, run the following commands to build the Cloudinary cartridges:

2. Open Demandware Studio.

3. Import these cartridges using the Import dialog:

   • int_cloudinary (the base cartridge)
   • int_cloudinary_sfra (the SFRA extension)
   • bm_cloudinary (the Business Manager extension allowing access to your Cloudinary Media Library)
   • cloudinary_sfra_changes (optional - a reference cartridge with changes made to the base cartridge to provide a reference implementation of the B2C Commerce cartridge on top of SFCC's demo site. You can use this to try out various features in the Cloudinary cartridge and see the code required.)
   • int_cloudinary_testsuite (optional - contains test harnesses for script APIs)
     
     
   Note

   If you're using the B2C Commerce Cartridge for Headless, import the int_cld_headless cartridge as well.

   

4. Link the cartridges to the sandbox. Select the sandbox connection, then select Properties. Select Project Reference and check in all except cloudinary_sfra_changes (as this is for reference only).

Configure settings

1. Go to Administration > Sites > Manage Sites. Select the relevant site, then select the Settings tab. In the cartridge path, add the int_cloudinary, int_cloudinary_sfra, cloudinary_sfra_changes (optional) and int_cloudinary_testsuite (optional) cartridges:
   
   
   Note

   If you're using the B2C Commerce Cartridge for Headless, add the int_cld_headless cartridge as well.
2. Add the bm_cloudinary cartridge to the cartridge path in Administration > Sites > Manage Sites > Business Manager - Settings:
   
   
3. Go to Administration > Site Development > Site Import & Export. In the Import section click Choose File:
   
   
4. Select cloudinary-metadata.zip in the metadata folder and click Open:
   
   
5. Click Upload:
   
   
6. Select cloudinary-metadata.zip in the Import section and click Import, then click OK:
   
   
   Notes

   • To avoid data errors while importing the cloudinary-metadata.zip file, Cloudinary related cartridges must be uploaded to the sandbox. If the code version is already active, reactivate the same code version when upload completes.
   • There is a folder called Sample content inside metadata that contains sample data for specific sites. If you want to import sample data for SFRA then import the RefArch.zip file by following the process above. This sample content works with the reference implementation in the cloudinary_sfra_changes cartridge, so you can optionally upload this if you are setting up the reference implementation.
7. For each of the Cloudinary jobs, go to Administration > Operations > Jobs and select a job, for example, Cloudinary - Upload content library assets. Select the Job Steps tab and update the scope to the site name:
   
   
   Note

   For the Cloudinary - Upload content library assets job, we recommend assigning only one site if the library is shared across multiple sites; however, if it is shared across multiple sites the job will process that library content multiple times but won't duplicate content in the Cloudinary Media Library.
8. Go to Administration > Organization > Roles & Permissions and select the specific user role (Administrator). Select the Business Manager Modules tab, then from Select Context choose your site and click Apply. In the list of Business Manager Modules, find Cloudinary Admin and click to update the permissions for Media Library and click Update:
   
   

Configure Cloudinary

Add structured metadata in Cloudinary

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

Enable resource listing in Cloudinary

In your Security page of the Cloudinary Console Settings, enable public resource listing by clearing the Resource list checkbox in Restricted media types.

Configure the cartridge site preferences

There are four Cloudinary custom site preferences groups as follows (found in Business Manager under Merchant Tools > Site Preferences > Custom Preferences):

• Cloudinary Core Configurations
• Cloudinary Asset Management Configurations
• Cloudinary Transformation Configurations
• Cloudinary Jobs Configurations

Cloudinary Core Configurations

Cloudinary Asset Management Configurations

Cloudinary Transformation Configurations

Cloudinary Jobs Configurations

Configure custom attributes

Cloudinary metadata contains custom attributes for System Object Types, which are added after successful import of the metadata. You can see the definition of the attributes under Administration > Site Development > System Object Types in each respective object type:

• Catalog
• Category
• Product
• Library

Catalog custom attributes

When you create or edit a catalog, you can set the following attributes in the Catalog Attributes tab:

Category custom attributes

When you create or edit a category, you can set the following attributes in the Category Attributes tab:

Product custom attributes

When you create or edit a product, you can set the following attributes in the General tab:

Library custom attributes

When you create or edit a library, you can set the following attributes in the Library Attributes tab:

Configure jobs

In Business Manager, navigate to Administration > Operations > Jobs.

After successful import of the metadata, these jobs are added:

• Cloudinary - Delta upload catalog assets
• Cloudinary - Delta upload library assets
• Cloudinary - Upload catalog assets
• Cloudinary - Upload content library assets
• Cloudinary - Upload product assets
• Cloudinary - Import image path and alt text

Cloudinary - Delta upload catalog assets

This job uploads recently changed catalog assets from SFCC to Cloudinary.

Cloudinary - Delta upload library assets

This job uploads recently changed content library asset files from SFCC to Cloudinary.

Cloudinary - Upload catalog assets

This job uploads catalog assets from SFCC to Cloudinary.

Cloudinary - Upload content library assets

This job uploads content library asset files from SFCC to Cloudinary.

Cloudinary - Upload product assets

This job uploads product asset files from SFCC to Cloudinary.

Cloudinary - Import image path and alt text

This job uploads product image paths (public IDs) and alt text from Cloudinary to SFCC.

Troubleshooting invalid steptypes.json files

B2C Commerce parses and loads the steptypes.json file at the following times:

• At server startup
• When the active code version is changed
• On sandboxes, each time a step is run.

If a steptypes.json file contains errors because of missing attributes or other problems, B2C Commerce logs the errors in an error file and does not register the custom step. B2C Commerce then loads steps from the steptypes.json files of other cartridges.

Invalid steptypes.json files cause messages like this to appear in Business Manager:

Invalid step [Step1]! Type with id [custom.MyCustomStep1] is unknown!

Configure services

In Business Manager, navigate to Administration > Operations > Services.

After successful import of metadata these services are added:

• cloudinary.rest.upload
• cloudinary.rest.list
• cloudinary.search.list

cloudinary.rest.upload

For RefArch.cloudinary.rest.creds:

1. Enter your base upload API URL in the URL field.
2. Enter your API Key in the User field.
3. Enter your API Secret in the Password field.

cloudinary.rest.list

For cloudinary.rest.list.creds:

1. Enter your base delivery URL in the URL field.
   • If you have a private CDN, this will be of the form:
     https://<cloud_name>-res.cloudinary.com
   • If you have a Custom Domain Name (CNAME), this will be of the form:
     https://<custom domain name>
   • Otherwise, add a placeholder for cloudname i.e. [cloudname]:
     https://res.cloudinary.com/[cloudname]
2. The User and Password fields do not need to be set.

cloudinary.search.list

For cloudinary.search.list.creds:

1. Enter your base search API URL in the URL field.
   https://[apikey]:[apisecret]@api.cloudinary.com/v1_1/[cloudname]/resources/search]
   
2. The User and Password fields do not need to be set.
3. cloudinary.search.list is used in a method. This method uses the service to get all resources based on tags, with the results presented in JSON format.

Make code changes

There are a number of code changes required to integrate Cloudinary into your Storefront application code. You can find all the changes in the cloudinary_sfra_changes cartridge.

Extra lines of code are either within // Custom Start and // Custom End comments, or have an inline comment starting // Custom.

To compile the JavaScript changes, run:

Load a Cloudinary image in a content asset

Open any content asset in which you want to load an image from Cloudinary, for example, open the about-us content asset, and add the following code to load a top hero banner background image from Cloudinary:

The query params are as follows:

• url: The relative URL of the image in Cloudinary. For Option 1, this is the path in the Media Library where the asset has been uploaded within the content folder (set in the Folder For Content Images In Cloudinary custom preference). For Option 2, this assumes that the Upload Content Assets job has been run to sync the asset into Cloudinary.
• pageType: The page type that is used to load responsive images including srcset and sizes attributes.
• isURL: Set to true if a transformed URL is to be loaded, or false if an image tag with srcset and sizes attributes is to be loaded.

Include the Cloudinary Video Player on a content page

Open any content asset in which you want to load a video from Cloudinary, for example, open the about-us content asset, and add the following code to load the Cloudinary Video Player:

The query param is:

• url: The relative URL of the video present in your static content library.

Cloudinary script APIs

The cartridge includes low level script APIs that are used by the cartridge itself to fetch assets from Cloudinary and apply transformations on the URLs. You can also use the APIs to customize the cartridge according to your needs, or make use of them in your own custom cartridges. Each of the methods has documentation in the code that explains the method's usage.

• cloudinaryApi: Use this API to communicate directly with Cloudinary APIs to fetch different types of assets and apply transformations on the URLs.
• cloudinaryTransformationApi: Use this API to provide transformations specified on several levels for different types of assets.

Site version for Cloudinary Test Suite

The cartridge, int_cloudinary_testsuite, is used to test script APIs that directly communicate with Cloudinary web services. To make it work for SiteGenesis, open cloudinaryConstants.js and set SITE_VERSION_FOR_TEST_SUITE to sfra.