Setup and configuration

This page provides instructions for setting up and configuring the SFRA and SiteGenesis cartridges. The instructions highlight the installation differences for each:

• SFRA: This is the recommended cartridge if you have an existing SFRA storefront or if you're new to Salesforce Commerce Cloud. SFRA represents the more recent architecture.

• SiteGenesis: If you have a SiteGenesis storefront and prefer not to migrate to SFRA, then the SiteGenesis cartridge is the suitable choice.

Set up the SFRA or SiteGenesis B2C Commerce Cartridge

Download the B2C Commerce Cartridge

You can download the certified SFRA or SiteGenesis 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

Install these cartridges:

• int_cloudinary (the base cartridge)
• bm_cloudinary (the Business Manager extension allowing access to your Cloudinary Media Library)
• int_cloudinary_testsuite (optional - contains test harnesses for script APIs)

For SiteGenesis:

• int_cloudinary_sg 
• cloudinary_sg_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.)

For SFRA:

• int_cloudinary_sfra 
• 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.)

For installation instructions, see the Adding custom cartridges section in the Exploring the Cartridge folder - SFRA Course.

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_sg, cloudinary_sg_changes (optional) and int_cloudinary_testsuite (optional) cartridges:

SFRA SiteGenesis

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 then 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 SiteGenesis then import the SiteGenesis.zip file by following the process above. This sample content works with the reference implementation in the cloudinary_sg_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 - Initial upload of content library assets. Select the Job Steps tab and update the scope to the site name:

Note
For the Cloudinary - Initial upload of 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 the Security page of your 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 - Initial upload of catalog assets
• Cloudinary - Initial upload of content library assets
• Cloudinary - Initial upload of 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 - Initial upload of catalog assets

This job drives the initial upload of catalog assets from SFCC to Cloudinary.

Cloudinary - Initial upload of content library assets

This job drives the initial upload of content library asset files from SFCC to Cloudinary.

Cloudinary - Initial upload of product assets

This job drives the initial upload of 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 SiteGenesis.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 delivery hostname (CNAME), this will be of the form:
     https://<custom delivery hostname>
   • 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.