Configuring an email rendering to output product content
This topic focuses on product recommendations but you can use the Email product recommendations rendering in other scenarios. With the SXA Storefront site template, by default, a recommended products email message is sent as part of the New Order Placed marketing automation campaign. This email message uses the Email product recommendations rendering, which is configured by default to use the shop name and order ID, or cart ID, custom values. The products that are proposed are determined based on the purchase history, the relationships defined in the catalog, or a list of products returned when executing a query against the catalog.
The rendering is implemented in a generic way to address multiple scenarios so that it accepts a list of product IDs and renders product content based on them. For example:
-
If you want to render a list of products in the email message based on a query, you can use the default implementation with a query configured as a parameter.
-
If you want to render content for a single product in a more descriptive way than showing a product, you must change the MVC View to select the first product returned from the configured query and output the markup you want.
For more advanced scenarios, you can override the virtual method in the rendering repository that retrieves the list of product IDs or inject custom pipeline processors to process and return a list of product IDs. You can also add additional parameters to the rendering.
As shown in the marketing automation campaign data flow, when customers submit an order, they are enrolled in the New Order Placed marketing automation campaign, which by default includes custom values (shop name and Order ID). When the Send Commerce Email marketing automation action is encountered, the custom values are passed to the Email Experience Manager (EXM) using the Message Bus. Then, when EXM starts to render the content of the email message, the shop name and order ID are passed onto the rendering as query parameters.
For the Abandoned Cart marketing automation campaign, the shop name and Cart ID are used.
The Email product recommendations rendering retrieves additional parameters from the data source for the rendering. The parameter item is based on the Recommended Products Email Parameters template (/sitecore/Templates/Feature/Commerce Experience Accelerator/Emails/Products/Email recommended products) and contains the fields detailed in the following table. If you require other custom parameters, you can use a customized copy of the default rendering parameter template.
|
Fields |
Description |
|---|---|
|
Product Page Link Text |
Text used for the go to product page button in the HTML markup. |
|
Products query |
The query used if an order ID is not passed in by EXM as a query parameter. See the GetRecommendedProducts pipeline. |
|
Max number of recommended products |
The maximum number of retrieved and rendered products. |
|
Related products field name |
The name of a relationship field as defined in the catalog and exposed in content where the recommended products are stored and retrieved from. If no value is specified, the fallback is to use the relationship field Note You can define any number of custom relationships in the catalog and expose them in content where they can be used for product recommendations. By default, four relationship fields are defined. |
The repository for the rendering executes the GetRecommendedProducts pipeline from the virtual GetProductsItemIDList method and uses the resulting list of product item IDs to render the product cards. 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.
Based on the list of product item IDs, the repository calls shared methods in the Commerce Foundation layer. This layer is also used by the Commerce renderings on the storefront site to build the final object model required to render the products, as well as the price and stock information. All methods in the repository are virtual, so you can override and customize them.
GetRecommendedProducts pipeline
By default, the GetRecommendedProducts pipeline contains three 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.
|
Processor |
Description |
|---|---|
|
|
This processor 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. |
|
|
This processor 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. |
|
|
This processor retrieves the contact’s last order ID and passes it to the recommended products provider. |
If the result of executing the pipeline is no list or an empty list of product IDs, the 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.
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.
GetRecommendedProductsPipelineArgs argument
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 |
|---|---|
|
|
Stores the resulting list of recommended products IDs. It does not contain a value initially. |
|
|
Stores a query that can retrieve product items from the index. |
|
|
Contains an integer indicating the maximum number of recommended products to retrieve and return in the |
|
|
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. |
|
|
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. |
|
|
Indicates whether the recommended products list is present and not empty. |
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.