The Recommended products pipeline

Abstract

Overview of the Recommended products pipeline and pipeline arguments.

Recommended products are supported two ways in SXA Storefront - they can be rendered as part of an email campaign or on the storefront site (using the Commerce Search Results rendering and a search scope). In both cases, the GetRecommendedProducts pipeline is used.

When the GetRecommendedProducts pipeline is executed, the resulting list of product IDs is used to render the product cards by retrieving the catalog items and products details and to compose the corresponding rendering model. The input to the pipeline is an argument object of type GetRecommendedProductsArgs. The result of executing the pipeline is a list of product item IDs, which are stored in the RecommendedProductsIdList  property of the pipeline argument object.

The following diagram shows how recommended products are determined in three scenarios:

  • When an email that recommends products is sent from a marketing automation campaign or using List Manager segmentation rules, the order ID is used to determine product recommendations. When there is no order ID in the EXM query parameters, the last order ID is retrieved from the ProductsQuery property or the Commerce Interactions cache.

  • When a bulk email campaign that recommends products is sent. In this case, the last order ID is retrieved from the ProductsQuery property or the Commerce Interactions cache.

  • When a search scope is used to display recommended products on the live storefront site. In this case, the recommended products are retrieved from the search scope results.

Note

The ScopeId is passed to the pipeline arguments only when rendering the Commerce Search Results rendering and associated search scope.

As soon as one of the pipeline processors succeeds when evaluating recommended products, the rest of the processors are ignored.

Get Recommended Products pipeline process

By default, the GetRecommendedProducts pipeline contains four processors as shown in the following table. They are executed in the order listed. If the conditions for the first processor are met, the processor retrieves the product item IDs and sets the RecommendedProductsIdList  property as well as the Success property to indicate that no further processing is required.

Before each processor starts to execute, it verifies if the RecommendedProductsIdList  property is already set. If so, it skips further processing and moves to the next processor in line. This means that if an explicit order ID is passed in as an argument, it takes precedence. It also means that if no explicit order ID is present and a query is specified and returns a result, no further processing is done. As a fallback, the last placed order for the current customer is looked up from the CommerceInteractionsCache facet for the contact when using the recommended products rendering in email campaigns; otherwise, when using the Commerce Search Results rendering, the fallback is to use the ScopeId.

Processor

Description

FromOrder

Uses the OrderId from the Email Experience Manager (EXM) campaign query string (in other words, from the campaign custom values) to retrieve the products list from the recommended products provider.

FromQuery

Goes to the Products query field from the rendering data source item and uses the search manager to run a query against the index to retrieve a list of items.

FromLastOrder

Retrieves the contact’s last order ID and passes it to the recommended products provider.

FromSearchScope

Retrieves the fallback scope ID and executes the query defined for the scope to determine the products to recommend.

With recommended product email messages, if the result of executing the pipeline is no list or an empty list of product IDs, the Product Recommendations rendering instead outputs ‘[CXA-DoNotSend]’ as part of the HTML markup to signal that the email message should not be sent. To avoid sending email messages that do not contain recommendations, the CheckForCommerceFlag processor verifies for the ‘[CXA-DoNotSend]’ text and abandons the EXM SendEmail pipeline if it does, so that an email message is not sent.

Important

In general, avoid injecting logic into renderings that EXM must process because there is no elegant way to stop EXM from sending out an email message. Best practices dictate that data used in the renderings should be retrieved before EXM renders the email message body. When an automated email campaign is triggered from a Marketing Automation campaign, the marketing automation action Commerce Email retrieves the data and passes it on as a custom value before EXM renders the email message body. When you use a regular email campaign to send a Recommended Products email message, the custom values are retrieved when the Recommended Products rendering is processed.

The rendering repository contains the GetRecommendedProductsPipelineArgs method that is called to populate the pipeline argument properties using the rendering data source, the custom parameters (order ID), and the query string parameters. The resulting object is passed to the pipeline.

The pipeline argument type contains the following properties:

Property

Description

RecommendedProductsIdList

Stores the resulting list of recommended products IDs. It does not contain a value initially.

ProductsQuery

Stores a query that can retrieve product items from the index.

MaxNumberOfRecommendedProducts

Contains an integer indicating the maximum number of recommended products to retrieve and return in the RecommendedProductsIdList property.

RelationshipFieldName

Passes the field name used by the provider.

The default provider implementation uses relationship fields on product items to select the recommended products. By default it uses the RelatedSellableItemToSellableItem relationship field. Another relationship field can be configured on the rendering parameters and passed into the pipeline.

Success

Indicates whether the recommended products list has been calculated successfully. Once a processor has retrieved a list of product IDs, it sets the value to True.

IsRecommendedProductsReady

Indicates whether the recommended products list is present and not empty.

Note

To customize how recommended products are determined, you can extend the GetRecommendedProducts pipeline and add new processors and custom properties. You do this by overriding the GetRecommendedProductsPipelineArgs method in the EmailRecommendedProductsRepository.