Introduction

This guide describes the steps you need to perform to display SPARQUE recommendations in the PWA.

For this purpose, you need:

• SPARQUE Desk

• SPARQUE Wrapper

• Intershop PWA 9.0.0

• ICM 14.0.1

References

• SPARQUE Search API Wrapper Documentation & API Reference

• SPARQUE Documentation | Defining Recommendation Strategies

Product Recommendations based on ICM Order Data

SPARQUE product recommendations can be displayed in the PWA based on order data following these steps:

1. Export order data from ICM

2. Use order data in SPARQUE

3. Display recommendations in the PWA

These are described in more detail in the following sections.

Export Order Data from ICM

1. Log in to the SMC

2. Select Schedules | Scheduling

3. Select Domain inSPIRED-inTRONICS for B2C or inSPIRED-inTRONICS_Business for B2B

4. Run ExecuteSparqueOrderProcessChain

The process chain exports orders from ICM without changing their status and pushes the export file to the Azure storage for SPARQUE (sparque4salessolution, sparqueb2c, or sparqueb2b.

The transport can be configured in the Intershop Organization Management for inSPIRED-inTRONICS_Business or inSPIRED-inTRONICS_Business:

For additional technical documentation, see Azure DevOps - icm-as-sparque | ICM Order Data Export to Azure File Storage.

Use ICM Order Data in SPARQUE

To make use of the ICM order data in SPARQUE and serve recommendations via the SPARQUE Wrapper API, create the following artifacts in SPARQUE Desk:

1. Data Pipeline to define the various recommendation types

2. Strategy and Endpoint to provide a list of all available recommendation types

3. Data Pipeline to import the order data

4. Strategies defining the business logic for each recommendation type

5. Endpoint for each recommendation type

Step 1 & 2 - Recommendation Types - Data Set, Strategy, and Endpoint

For steps 1 and 2, follow the description in SPARQUE Documentation | Defining Recommendation Strategies and update the result descriptions as shown there.
Ensure that each recommendation type is consistently named and documented so that it is easy to discover via the listing endpoint.

Step 3 - Import Order Data into SPARQUE

Import the order data into the “Intershop Customer Data” Dataset (SPARQUE Documentation | Datasets):

1. Use the “Fetch a file from URL” option to point to the ICM export stored in Azure.

2. Start with a simple mapping to create core entities. Expand this mapping as needed for additional strategies.

Example XSLT mapping that derives order, product, user, and customer objects from the exported ICM order file:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:spinque="com.spinque.tools.importStream.EmitterWrapper"
    xmlns:su="com.spinque.tools.importStream.Utils"
    xmlns:ns2="http://www.intershop.com/xml/ns/intershop/order/2.0" extension-element-prefixes="spinque">

    <xsl:output method="text" encoding="UTF-8"/>

    <xsl:variable name="rdfstype">http://www.w3.org/1999/02/22-rdf-syntax-ns#type</xsl:variable>
    <xsl:variable name="host">https://www.sparque.ai/</xsl:variable>
    
    <!-- channel -->
    <!--<xsl:variable name="channelprefix">ish</xsl:variable>-->
    <xsl:variable name="channelprefix">
        <xsl:variable name="channelprefix-after" select="substring-after(//ns2:store, '-')" />
            <xsl:choose>
                <xsl:when test="contains($channelprefix-after, '-')">
                    <xsl:value-of select="substring-before($channelprefix-after, '-')"/>
                </xsl:when>
                <xsl:otherwise>
                    <xsl:value-of select="$channelprefix-after"/>
                </xsl:otherwise>
            </xsl:choose>
    </xsl:variable>

    <xsl:template match="/ns2:order">
        <xsl:variable name="orderID" select="su:uri($host, $channelprefix, 'order', //ns2:document-no)"/>
        <spinque:relation subject="{$orderID}" predicate="{$rdfstype}" object="{$host}Order"/>
        <spinque:relation subject="{$orderID}" predicate="order-channel" object="{su:uri($host, 'channel', $channelprefix)}" />

        <!-- Customer information -->
        <xsl:variable name="customerID" select="su:uri($host, $channelprefix,'customer', ns2:order-header/ns2:customer/ns2:customer-id)"/>
        <spinque:relation subject="{$customerID}" predicate="{$rdfstype}" object="{$host}Customer"/>
        <spinque:relation subject="{$orderID}" predicate="order-customer" object="{$customerID}"/>

        <!-- User Information -->
        <xsl:variable name="userID" select="su:uri($host, $channelprefix, 'user', ns2:order-header/ns2:customer/ns2:user-id)"/>
        <spinque:relation subject="{$userID}" predicate="{$rdfstype}" object="{$host}User"/>
        <spinque:relation subject="{$orderID}" predicate="order-user" object="{$userID}"/>

       <xsl:for-each select="ns2:order-items/ns2:order-item">
            <!-- Lineitem -->
            <xsl:variable name="lineitem" select="su:uri($host, $channelprefix, //ns2:document-no,'lineitem', @id)"/>
            <spinque:relation subject="{$lineitem}" predicate="{$rdfstype}" object="{$host}Lineitem"/>
            <spinque:relation subject="{$lineitem}" predicate="lineitem-order" object="{$orderID}"/>

            <!-- Product Relation -->
            <xsl:variable name="productID" select="su:uri($host, $channelprefix, 'product', ns2:item-product/ns2:product/ns2:sku)"/>
            <spinque:relation subject="{$lineitem}" predicate="lineitem-product" object="{$productID}"/>
        </xsl:for-each>

        <xsl:for-each select="ns2:order-items/ns2:order-item">
            <!-- Product -->
            <xsl:variable name="productID" select="su:uri($host, $channelprefix, 'product', ns2:item-product/ns2:product/ns2:sku)"/>
            <spinque:relation subject="{$productID}" predicate="{$rdfstype}" object="{$host}product"/>
            <spinque:relation subject="{$productID}" predicate="product-order" object="{$orderID}"/>
        </xsl:for-each>
    </xsl:template>

</xsl:stylesheet>

Step 4 & 5 - Recommendation Strategies and Endpoints

Top Seller Recommendations

A simple strategy that:

• Aggregates products across orders

• Ranks by the number of orders containing each product

• Returns product data for the top 10 SKUs

The endpoint should be set up like this:

recommendation_best_sold -> OBJ

Product Detail Recommendations

Given a single SKU, this strategy:

• Finds products most frequently purchased together with the input SKU (same order)

• Ranks by co-purchase count

• Returns the top 10 related products

The endpoint should be set up like this:

recommendation_product/p/CurrentProductId/{STRING} -> OBJ

Cart Recommendations

Similar to product detail recommendations, but supports multiple SKUs as input.

Notes:

• The CartProductIds parameter in the Wrapper’s recommendations endpoint is forwarded to SPARQUE as cartid.

• You can use cartid flexibly for either cart IDs or product SKUs (as in this example).

The endpoint should be set up like this:

recommendation_basket/p/cartid/{TUPLE_LIST} -> OBJ

Display Recommendations in the PWA

The display of SPARQUE product recommendations is based on the maintenance of the CMS component Product List (SPARQUE Recommendations) in Intershop Commerce Management. You can maintain different components for different strategies.

CMS Recommendations Component Configuration Parameters

Get Recommendation Strategies for Configuration Parameter Strategy

The list of available recommendation strategies can be determined using the /config endpoint of the REST API of the SPARQUE Wrapper returning the recommendationStrategies, where you need to use the value of strategy, see SPARQUE Documentation | Defining Recommendation Strategies.

Example URL (replace the placeholders with your settings accordingly):
<https://<server>>/api/<version>/config?apiName=<apiName>&channelId=<channelId>&workspaceName=<workspaceName>&Locale=<Locale>

Example Strategies

The following strategies are currently available in the workspace “intershop-project-base-v2”:

Placement Limitations in the PWA

You should place the CMS recommendation components only in areas where the necessary information for the recommendation request is available.