HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Catalog content provider

Describes how to use content providers in Optimizely Commerce (PaaS).

The content provider technology is a powerful integration method for extracting content from different sources and make it available on a website, providing an integrated user experience.

A content provider is an integration method used for example to extract content from external sources and make it available in Optimizely. In Optimizely Commerce (PaaS), the catalog content provider is used for building the integration between the Commerce (PaaS) catalog system and the Optimizely Content Management System (CMS).

Classes in this topic are available in the following namespaces:

  • EPiServer.Commerce.Catalog
  • EPiServer.Commerce.Catalog.ContentTypes
  • EPiServer.Commerce.Catalog.Provider

Basic concepts

In Commerce (PaaS), you can make product catalog data available inside the CMS Edit view. Editors can drag and drop product content into page or block content areas. They can also edit and manage the catalog content through an interface that has the same look and feel and similar interaction patterns as the CMS Edit view.

The ECF Catalog system consists of the following parts:

  • Catalog. Can contain either NodeContent or EntryContent; the biggest element in the Catalog system.
  • NodeContent. Can be the child of a Catalog or another CatalogNode and the parent of CatalogEntries or other CatalogNode(s).
  • EntryContent. Must be the child of a Catalog or CatalogNode, and cannot be the parent of anything else. You can move, copy, or link CatalogNode and CatalogEntry only within a Catalog.

The Commerce (PaaS) content root integrates the ECF Catalog system, which is the root content of the CMS catalog system. The Commerce (PaaS) content root can only include Catalog; CatalogNode and CatalogEntry are prohibited.

Use standard Optimizely APIs to work with commerce content in the CMS. The provider handles the mapping to and from ECF.

Load a product

//Get the currently configured content loader and reference converter from the service locator
    var contentLoader = ServiceLocator.Current.GetInstance<IContentLoader>();
    var referenceConverter = ServiceLocator.Current.GetInstance<ReferenceConverter>();
    
    //Get the correct product id as it's represented in EPiServer Commerce
    //In this example we arbitrarily use the integer 1
    var productIdFromCommerce = 1;
    
    //We use the content link builder to get the contentlink to our product
    var productLink = referenceConverter.GetContentLink(productIdFromCommerce, CatalogContentType.CatalogEntry, 0);
    
    //Get the product using CMS API
    var productContent = contentLoader.Get<CatalogContentBase>(productLink);
    
    //The commerce content name represents the name of the product
    var productName = productContent.Name;

Get children of a category

//Get the currently configured content loader and reference converter from the service locator
    var contentLoader = ServiceLocator.Current.GetInstance<IContentLoader>();
    var referenceConverter = ServiceLocator.Current.GetInstance<ReferenceConverter>();
    
    //Get the correct category id as it's represented in EPiServer Commerce
    //In this example we arbitrarily use the integer 1
    var nodeIdFromCommerce = 1;
    
    //We use the content link builder to get the contentlink to our product
    var productLink = referenceConverter.GetContentLink(nodeIdFromCommerce, CatalogContentType.CatalogNode, 0);
    
    //Get the children using CMS API
    var children = contentLoader.GetChildren<CatalogContentBase>(productLink);

Determine the catalog content type

In the ECF catalog system, Catalog/Node/Entry are stored in different tables, which means they might end up having the same ID. To resolve this, the Commerce (PaaS) content provider reverses the two most significant bits (MSB) to determine which type of catalog content is being used.

When converting from a Commerce (PaaS) content ID to a content link, you add two more bits to the left of the ID. When converting from a content link back to a Commerce (PaaS) content ID, the two MSBs are cleared out. You can use the ReferenceConverter to perform these actions.

public void ConversionSampleCode(CatalogContentBase content)
      {
        var catalogContext = CatalogContext.Current;
        var referenceConverter = ServiceLocator.Current.GetInstance<ReferenceConverter>();
        if (content is EntryContentBase)
          {
            //convert from ContentReference to catalog object id
            var entryId = referenceConverter.GetObjectId(content.ContentLink);
            var entry = catalogContext.GetCatalogEntryDto(entryId, 
                new CatalogEntryResponseGroup(CatalogEntryResponseGroup.ResponseGroup.CatalogEntryFull));
    
            //do something with the entry
    
            //Covert from catalog object id to ContentReference
            var contentType = referenceConverter.GetContentType(content.ContentLink);
            var contentLink = referenceConverter.GetContentLink(entryId, contentType, 0);
          }
      }

EntryContent can be one of four subclasses:

  • VariationContent
  • ProductContent
  • PackageContent
  • BundleContent

Related blog post: External Catalog – Chapter 1: The Catalog Content Provider