Catalog mappings commands and pipelines

Current version: 10.2

Catalog mappings represent relationships from Sitecore content items (in the Sitecore Content Editor) to the original corresponding Commerce Engine Catalog items.

It is possible for a catalog sellable item to appear in multiple locations within the Content Editor content tree. This happens, for example, when a sellable item appears under multiple categories. Because the Sitecore platform expects every item in the content tree to have a unique identifier (represented by the Item ID property in Content Editor), each occurrence of the same catalog item has a different Item Id value. In order to map and resolve these different instances of the same catalog item back to the original catalog entity ID, Commerce Engine Connect uses a catalog mappings system. The Catalog plugin defines commands and pipelines that allows retrieval of catalog mapping information.

Catalog mappings commands and pipelines

The following table describes the catalog mappings commands and pipelines:

Command/Pipelines

Description

GetMappingsFromDbCommand

GetCatalogMappingsPipeline

Returns the content of the Catalog Mappings table for catalog selected in Sitecore Content Editor.

GetMappingsForIdFromDbCommand

GetCatalogMappingsForIdPipeline

Returns the list of all catalog mappings (in bulk) for the specified SitecoreID.

Parameters:

  • SitecoreID: an ID that represents a one-to-one relationship with a Commerce entity ID, and a one-to-many relationship with Item IDs in Sitecore (known as deterministicIDs in the catalog mappings system).

The Commerce Engine Connect uses the GetCatalogMappingsForId method to fetch catalog mappings in batch of 20 (the default batch size is 20, but it is configurable), and refreshes the mappings of single catalog items in the content tree (which may appear in multiple locations in the Content Editor content tree).

The method uses the sitecoreId to discover the original Commerce Engine item (Entity ID) to which the Sitecore item (a deterministic ID) is mapped. The Commerce Engine then uses the original entity Id to construct a table of all the deterministic IDs for the item in Sitecore, and then returns the content to the caller.

This method is useful, for example, when a single item is updated in the XC Business Tool (for example, when a new Catalog entity version is added). It is also used as part of the incremental indexing process.

Mapping Commerce entity ID to Sitecore Item ID

Catalog entities defined in the Catalog plugin inherit the Commerce entity ID property from the core CommerceEntity class, but also have a SitecoreId property derived from the CatalogItemBase entity class. The SitecoreId property is used internally by the mappings system to generate the deterministic identifier used as the Sitecore Item Id in Content Editor. In the catalog mappings system, the SitecoreId property represents a one-to-one relationship with the Commerce Entity ID, and a one-to-many relationship with catalog Item Id properties in the Content Editor.

The following show an example of the method that generates the SitecoreID value:

RequestResponse
SitecoreId = GuidUtility.GetDeterministicGuidString(categoryId)SitecoreId = GuidUtility.GetDeterministicGuidString(sellableItemId),

Using the Sitecore Id property in custom methods

If you use a custom method to create a Catalog item entity, you must ensure to always include both the Commerce entity Id and the SitecoreId = GuidUtility.GetDeterministicGuidString(entityId) properties. This is required to generate the deterministic ID value that the mappings system needs to resolve the Catalog item in the Content Editor back to the matching Commerce entity, for example:

RequestResponse
...  
  {
   sellableItem.Id = entityId;
   sellableItem.FriendlyId = productId;
   sellableItem.SitecoreId = GuidUtility.GetDeterministicGuidString(entityId);
   ...
  }
...

Do you have some feedback for us?

If you have suggestions for improving this article,