Salesforce Commerce Cloud Site Cartridge

Overview

Salesforce Commerce Cloud (formerly Demandware), is one of the industry's most agile and scalable e-commerce platforms. Cloudinary offers a certified Salesforce Commerce Cloud (SFCC) cartridge that enables you to simplify and automate the process of transforming, optimizing, finding and delivering metadata-enriched images and videos throughout your entire Commerce Cloud store, including product images and videos, category assets, and site catalogs.

Site Cartridge Video Tutorials

To get an idea of the functionality provided by Cloudinary in the site cartridge, watch the following videos that cover:

  • An overview of what the cartridge offers
  • Installation and configuration information
  • The different modes of operation
  • How videos can be used within your site

Supported architectures

Cloudinary offers a site cartridge for each of SFCC's reference architectures: SiteGenesis, and Storefront Reference Architecture (SFRA). Both have the same functionality, but are configured in different ways.

SiteGenesis site cartridge

If you already have a storefront on SiteGenesis and you do not want to migrate to SFRA, then this is the cartridge for you.

SiteGenesis site cartridge installation

You can download the certified SiteGenesis site cartridge from the Cloudinary page on the SFCC Link Marketplace (requires SFCC login). Installation and basic usage instructions are provided in the download - see Cloudinary SiteGenesis LINK Documentation in the documentation folder. You can also get the most recent release from Cloudinary's GitHub repo.

SFRA site cartridge

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

SFRA site cartridge installation

You can download the certified SFRA site cartridge from the Cloudinary page on the SFCC Link Marketplace (requires SFCC login). Installation and basic usage instructions are provided in the download - see Cloudinary SFRA LINK Documentation in the documentation folder. You can also get the most recent release from Cloudinary's GitHub repo.

Media mapping options

Depending on your setup, there are three options for media mapping and delivery using Cloudinary:

Option 1 - media directly uploaded to Cloudinary (recommended)

  • Cloudinary is the single source of all media for all catalogs.
  • For the product catalog, assets in Cloudinary are mapped to products in SFCC using tags and structured metadata.
  • For the content and site catalogs, specify URLs to Cloudinary assets in content slots.
  • If migrating from an existing site, you can run jobs to bulk upload your media to Cloudinary. Tags and structured metadata are automatically added to the assets in Cloudinary for the product catalog.
  • Cloudinary's Product Gallery can be used.
  • Cloudinary's Video Player can be used.

Option 2 - media uploaded to SFCC and copied to Cloudinary

  • SFCC is the source of mapping for all media for all catalogs.
  • For the product catalog, assets are expected to reside in Cloudinary using the same paths as in SFCC, so that assets are ultimately delivered from Cloudinary. You can run jobs to upload and synchronize your media residing in SFCC to Cloudinary.
  • For the content and site catalogs, specify URLs to Cloudinary assets in content slots.
  • Cloudinary's Product Gallery can be used.
  • Cloudinary's Video Player can be used, but requires extra configuration.

Option 3 - media fetched to Cloudinary on demand

  • Media is automatically uploaded from its existing location to Cloudinary, when requested by the end user, and subsequently delivered from Cloudinary.
  • This option is not recommended as it does not provide the same asset management benefits as the other two options, but exists to provide a quick and simple way to deliver your media from Cloudinary.

If you decide to implement your media mapping using one option, then at a later stage decide to use a different option, you should contact support to discuss migration paths.

Jobs

In SFCC, jobs are used to automate routine tasks or long-running processes. You can run them manually or schedule them to run at specific times.

The site cartridge contains the following jobs, which are primarily used for Option 2 - media uploaded to SFCC and copied to Cloudinary, but can also be used for Option 1 - media directly uploaded to Cloudinary if migrating from an existing site:

  • Upload Product Assets

    • This job uploads all product assets (images and videos) from the product catalog into Cloudinary.
    • By default, the view type configured as the high-resolution source of images and “swatch” are uploaded, but you can also configure other view types to be uploaded.
    • Tags and structured metadata are applied to the uploaded assets.
  • Upload Catalog Assets

    • This job uploads all catalog assets (images and videos) from the product catalog into Cloudinary.
  • Upload Content Assets

    • This job uploads all content assets (images and videos) from the content catalog into Cloudinary.
    • If a content catalog is shared by multiple sites, you only need to run this job in the context of one of the sites to avoid unnecessary duplication of uploads from multiple job executions from multiple sites.

For each of the jobs, the root upload location in Cloudinary is specified in the custom preferences for the Cloudinary cartridge in SFCC, and the SFCC folder structure is automatically replicated in Cloudinary. You can use each of the jobs both to migrate all your SFCC media assets into Cloudinary and also subsequently to upload only new assets created in SFCC.

Tags and structured metadata

If using Option 1 - media directly uploaded to Cloudinary, assets need to have particular tags and metadata based on the product catalog definitions in SFCC to identify all assets belonging to products and variants. These can be added directly into Cloudinary, in the DAM, as described below. When product images and videos are uploaded to Cloudinary using the Upload Product Assets job, the required tags and structured metadata are automatically assigned to them.

Assigning tags to product assets

There are three different tag types that can be assigned to assets:

  • Product tag: This tag is the unique product identifier, which could be the product's ID, or some other unique identifier, such as UPC or SKU. Use the SFCC custom preference, CLDProductAttributeForTags, to indicate to the cartridge which attribute to use as the identifier. By default it is set to ID.

    In the example shown here, the tag name is 25721034M, as this is the ID for the product:

    Product page showing ID
    When displaying images and videos on a product page, the gallery automatically pulls in all assets with the same product tag.

    Note
    The Upload Product Assets job uses CLDProductAttributeForTags to assign the product tag automatically. Should you wish to override this global setting, you can specify the tag name itself on a per-product basis, using the Cloudinary Tag Name (CLDTagName) attribute (in the Cloudinary section of the product settings). Any assets in Cloudinary that have this tag will appear in that product's gallery.

  • Variation product tag: This tag identifies particular variations of a product. In the example section below, there are two color variations of the product, Sundried Coral and Navy Sky. Each variation has its own set of images, so when the customer selects a color, the relevant images for that color are displayed in the gallery. The tag used for these product types takes the form: <master-product-tagname>-<variation-color-value-id>, where <master-product-tagname> is the unique product identifier, and <variation-color-value-id> is the color ID of the variation.

    Note
    You can find the variant color IDs as follows:

    1. In Business Manager, open the product and click the Variations tab.
    2. In the Variation Attributes section, click the color attribute.
    3. See the values in the Defined Variation Values for color section.

      Defined variations
    Important
    Only images are supported for product variations, not videos.
  • Variation product swatch tag: This tag identifies the swatch image for a product variation. The tag used for swatch images takes the form: <master-product-tagname>-<variant-color-value-id>-swatch. Swatch images are used by the customer to select the color they want. The images displayed in the product gallery are based on the selected swatch.

    Swatch selection

Assigning structured metadata to product assets

The site cartridge requires you to add structured metadata fields to your Cloudinary account, as follows:

Structured metadata fields

Important

  • The Upload Product Assets job automatically populates these fields, so you must add the fields marked mandatory in the table below to your account before running the job.
  • The external ID and label of each field must match those shown in the table.

Example images showing tags and structured metadata

The following table shows all the images stored in Cloudinary that are associated to the product with the unique identifier, 25721034M. Each has its own set of tags and structured metadata. Where the same tag is used for multiple images, these are shown together in the same product gallery.

On the product listing page you can see the master product image and both swatch images:

Main product image on product listing page

This is the product page, showing the product gallery, with the Navy Sky variation of the product selected:

Product gallery on product page

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.

Transformations

All Cloudinary image and video transformations can be applied at various levels in your store, with the transformations for the most specific level taking precedence. So, for example, a transformation set that includes a text overlay showing 50% Off for an image on the product level will override a transformation set with a text overlay saying 25% Off that was set for an image on the catalog level.

The cartridge also includes special functionality for adding responsive behavior to your images to make sure that the optimal image size is delivered to each user based on the available space on their viewing device.

Commonly-used Media Library features

With the site cartridge installed, you can open your Cloudinary Media Library from Merchant Tools > Cloudinary Admin > Media Library. You can access almost all of the same functionality as is available in the full Media Library in your account console.

Advanced search

The advanced search lets you search by things like tags, metadata, format, orientation, resolution, or (if supported for your account), even by image analysis characteristics, such as prominent colors, presence of faces, or image location.

Media Library advanced search

For more details, see Advanced search in the Digital Asset Management guide.

Collections

Collections are ad-hoc groupings of images. Images can be added to and from collections without affecting or moving the image itself, and images can be included in multiple collections. You can create your own collections (assuming you have the required permissions) or other Cloudinary users can share collections with you.

Collections can often be a convenient way to group all images that you might want to use on a particular project or campaign. You can access collections from the Navigation button at the top left of the Media Library.

Media Library collections

For more details, see Collection management in the Digital Asset Management guide.

Tagging and metadata

Assets that have tags and other metadata enable all Media Library users to better organize and search for assets in the Media Library.

In addition to the option to specify tags when you upload an image, you can also add or edit tags and other metadata after images are uploaded via the embedded Media Library, and even set the same tags or metadata on multiple images at once.

You can view and set this data using the Asset toolbar or in the Asset management page.

Asset toolbar

You can set tags and metadata for several selected assets at once from the main Media Library view using the Tag or Edit Metadata options in the asset toolbar. The type of metadata available for editing (contextual or structured) depends on the settings for your organization's account.

Media library asset toolbar

Asset management page

You can view or edit tags and metadata as well as view embedded image metadata for a specific asset from the Summary and Metadata tabs of the Asset management page.

To open the Asset management page either click on the asset or select Manage from the asset's context (right-click) menu.

Media library asset management

Tip
From the Asset management page, for images you can also select to insert a pre-defined transformation of the original asset (a 'Transformation Preset'), view or activate a variety of image analysis options in the Analysis tab, and more. For details, see Asset management drill-down in the Digital Asset Management Guide.

Media editor

The media editor is only applicable to images and is accessible from the Asset management page, by clicking the Edit Image button.

In the media editor you can crop and resize your image to suit your design. If you save the modified image, your current asset will be overwritten. You can retrieve the original if you have backups enabled, otherwise, you may prefer to download the modified image and upload it as a new asset.

Media library media editor

Transformation editor

The transformation editor is accessible from the Asset management page, by clicking the Transform button.

In the transformation editor you can apply and preview various transformations, then click Insert to return to the Page Designer that will show your transformed asset. Unlike when using the media editor, your original asset remains unmodified.

Media library transformation editor

For more details, see Asset and transformation editing in the Digital Asset Management guide.

✔️ Feedback sent!

Rate this page: