catalog – Andrew Sutherland's Blog

Reading Time: 6 minutes

In this article, we will review and compare catalogs and categories between Sitecore Experience Commerce and OrderCloud to facilitate developers looking to transition from XC to OrderCloud as well as identify a path for migration of existing XC solutions to OrderCloud.

We will look at a high-level comparison of architecture, functionality, and data models, with greater focus on transitioning from Sitecore Experience Commerce, meaning identifying a close path to parity in OrderCloud, using the Habitat catalog and SXA Storefront.

Conceptual Architecture and Features

Catalogs and Categories

In XC, the structure of catalogs, categories, and sellable items/products can be recreated in OrderCloud. In a nutshell, categories are tied to their catalogs and can only have one parent, either another category or the catalog itself, while sellable items or products are separate to the catalog and can be assigned to one or more catalogs and/or categories.

In earlier versions of XC categories were allowed to have multiple parents, but support was subsequently removed. If an XC solution still contains categories with multiple parents this would be a consideration for pre-migration cleansing.

Figure 1: XC relationships between catalogs, categories, and sellable items.

Figure 2: OrderCloud relationships between catalogs, categories, and products.

The Storefront to Catalog Association

In Customer to Buyer Users we discussed that in XC, a storefront was required in order to associate a customer to a catalog. while OrderCloud has a direct assignment between buyers and catalogs. We will now revisit this to complete the context for catalogs.

In the SXA storefront, only a single catalog can be associated to the storefront, which is configured in the Content Editor under /sitecore/content/<tenant>/<site>/Home/Catalogs.

Figure 3: An example catalog configuration for a storefront.

Over in OrderCloud, a catalog assignment creates a link between a catalog and a buyer, bypassing the need for a storefront.

Figure 4: XC associates a catalog to a site while OrderCloud assigns catalogs directly to a buyer

The catalog assignment also contains two additional boolean properties in ViewAllCategories and ViewAllProducts, which as the names suggest allow all categories and products to be viewed by buyer users via the /me/products resource. These properties are important when understanding how XC customers can view sellable items vs OrderCloud buyers viewing products, which we cover in the next section SXA Scope Query vs Product Visibility.

SXA Scope Query vs Product Visibility

Now that we have established that the catalog structure can be identical between XC and OrderCloud, how do both systems handle product search functionality?

In an SXA storefront, there are two primary search scopes that are used for searching sellable items; the catalog scope and the category scope. These scopes are defined in the Content Editor under /sitecore/content/<tenant>/<site>/Settings/Scopes.

Figure 5: The catalog and category scopes in an SXA storefront.

Catalog Scope

The catalog scope is used by the global site search component, and will perform a search query returning all active sellable items associated to the catalog. An optional search term can be provided by the storefront user to further filter the results.

Referencing OrderCloud’s documentation, Product Visibility Requirements, we see Scenario 3 replicates the XC and the SXA storefront visibility rules for the catalog scope, excluding the search term filter. “When I assign a catalog to a buyer organization, I just want everybody in that organization to see everything in the catalog.” In short the ViewAllCategories and ViewAllProducts of a catalog assignment should be set to true.

Category Scope

The category scope is used for the category search results page and is just a more refined scope than the catalog scope in that it will return all active sellable items associated to a specific defined category. Again, an optional search term is available for further filtering.

The Search Term Filter

For the search term filter, the SXA query builder appends a comparison between the search term appends a fuzzy query against the sxacontent index field, which is an array consisting of the following sellable item properties:

Tags
ProductId
Name
DisplayName
ItemDefinition
Brand

The resulting query for a global search will look something like the following, with the highlighted section representing the example search term of “Spectra”.

7512 07:28:09 INFO  Solr Query - ?q=((((((((commercesearchitemtype_t:("sellableitem") AND _latestversion:("True"))
AND excludefromwebsitesearchresults_b:("False")) AND parentcataloglist_sm:("59ddadc19b88727e9e143f6cf321ae0f"))
AND (_path:("ccd5fda3aaba4f46b4f9b8bb7938bae5") AND searchable_b:("True")))
AND (sxacontent_txm:(*Spectra*) OR sxacontent_txm:("Spectra")))
AND _language:("en")) AND _latestversion:("True"))
AND ((_displayname:(*Furry*))^1000 OR (-_name:("")  _name:[* TO *]))) AND _val_:__boost&amp;amp;amp;amp;start=0&amp;amp;amp;amp;rows=0&amp;amp;amp;amp;fq=_indexname:(sitecore_web_index)&amp;amp;amp;amp;wt=xml

In OrderCloud, we can achieve an equivalent query using the /me/products resource and applying a filter that allows us to filter on multiple fields with logical “OR” syntax to query each of the raw OrderCloud properties that make up the XC sxacontent index field.

Catalog scope: /me/products?catalogID=Habitat_Catalog&ID|Name|xp.Tags|xp.ItemDefinitions|xp.Brand=*Spectra*
Category scope: /me/products?catalogID=Habitat_Catalog&categoryID=Televisions&ID|Name|xp.Tags|xp.ItemDefinitions|xp.Brand=*Spectra*

As we will review in an upcoming article, the Name property tends to be a duplicate of the DisplayName, so we won’t bloat the product’s xp in OrderCloud with redundant data, however you can choose to include the Name property and amend the /me/products queries as necessary.

Catalog – Item Definitions

Item definitions allow composer templates to be associated with sellable items to create extended properties on the sellable items. The name of the item definition is also used in storefront search indexes for search components

From an OrderCloud perspective, extended properties (XP) can be used to represent an equivalent result. As represented in figure 6, all item definition properties are merged into a consistent xp schema along with the item definitions as its own xp, which will be indexed and available for search queries, product facets, etc.

Figure 6: The XC architecture for item definitions vs a sample architecture approach in OrderCloud.

Other Considerations

Entity Versioning and Workflow

In lieu of entity versioning in OrderCloud, one approach towards migration is to only migrate the latest published versions of catalogs and categories. In a similar manner the publishing workflow that applies to catalogs and categories may see a project consider the latest entity version as the source of truth regardless of its published state. Considerations would need to be made on project by project basis, which may entail a level of data cleansing.

Catalogs and Categories Pending Purge

A gotcha in migrating catalogs and categories is that the entities can still exist if they are pending purge, which is represented on the entity with an instance of PurgeCatalogsComponent or PurgeCategoriesComponent. These entities can be safely ignored during migration.

Property Localisation

XC provides entity properties to be localisable for content that can be displayed in multiple languages. OrderCloud does not explicitly support property localisation, however localisation can be achieved by creating locale-specific entities as documented in How to Globalize your eCommerce.

Data Mapping

With the conceptual analysis above, we will now review what data mapping would look like for migration and from a comparison standpoint.

In the XC Entity/Component column, components are assumed to live on the primary XC entity being mapped.

OrderCloud IDs do not allow spaces. It is important that the IDs are parsed to remove/replace invalid characters consistently.

Catalogs

Catalog mapping is fairly basic as there aren’t many properties on the catalogs of either system

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
ID	string	Yes	Catalog	FriendlyId	string
OwnerID	string	No	N/A	N/A	N/A
Name	string	Yes	Catalog	DisplayName	string
Description	string	No	N/A	N/A	N/A
Active	boolean	No	Catalog	Published	boolean	This assumes only the latest published entity version is being migrated.
xp	object	No	N/A	N/A	N/A	XC composer views and programatic components can be added to xp as needed.

Catalog Assignments

Catalog assignments are simply a relational mapping with the added control over category and product visibility.

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
CatalogID	string	Yes	Catalog	FriendlyId	string
BuyerID	string	No	N/A	N/A	N/A	The Sitecore Domain taken from the Storefront with the associated catalog.
ViewAllCategories	boolean	No	N/A	N/A	N/A	Set to true.
ViewAllProducts	boolean	No	N/A	N/A	N/A	Set to true.

Tag: catalog

Transitioning from Sitecore Experience Commerce to OrderCloud: Catalogs and Categories