Introduction

The XO Algorithm Orchestrator is a powerful tool that allows Data and Merchandising teams to collaboratively curate highly effective and brand-specific recommendation strategies. These recommendation strategies are based on algorithms and form an essential part of merchandising rules.

A merchandising rule combines recommendation strategies, constraints - such as filters and weighting - and triggering. One or more merchandising rules can be combined to form a recommendation widget.

The XO Algorithm Orchestrator allows you to use algorithms from different sources to power your recommendation strategies. To do so, the Data team creates strategy templates in the XO Algorithm Orchestrator. The Merchandising team can then configure these templates and use them as part of a merchandising rule.

The following sections are intended for Data team members with admin user rights in the XO console. We discuss:

• General information about the XO Algorithm Orchestrator
• Bring Your Own Algorithm: How to use your in-house algorithms to power recommendation strategies
• How to create a recommendation strategy templates based on an algorithm

Algorithm sources

Algorithms form the basis of any recommendation strategy that can be used in a merchandising rule. The Data team creates one or more strategy templates in the XO Algorithm Orchestrator, which are then configured by the Merchandising team. Once configured, these templates become recommendation strategies. This collaborative process between the Data and Merchandising teams ensures optimal outcomes for end-users.

The XO Algorithm Orchestrator supports the usage of algorithms from three different sources:

• XO algorithms - Some XO algorithms are provided by default while others are subject to compensation, such as GPT-based algorithms.
• Third-party algorithms - For more information on how to implement third-party algorithms, reach out to our Customer Support.

• Your in-house algorithms - Bring Your Own Algorithm: You can implement your own custom, in-house created algorithms tailored to your specific needs.

Strategic frameworks

The Merchandising team has the flexibility to combine various recommendation strategies to create a recommendation widget on the widget configuration page in the XO Console. You can combine strategies using either a Fallback framework or a Hybridization framework.

Fallback framework

The Fallback framework ensures that alternative strategies and, thus, potentially algorithms, are called if the primary strategy doesn’t produce the desired results. In this framework, you define a hierarchy of strategies, each functioning as a fallback option for the preceding one. In other words, if strategy A fails to produce sufficient results, be that with regards to quality or quantity, strategy B is invoked instead.

Hybridization framework

The Hybridization framework allows you to mix strategies and thus, potentially algorithms. While each strategy provides a score for each individual item, using the Hybridization framework allows you to combine these scores to define a new ranking for any given product based on all scores provided by the strategies used.

Hosting and deploying your in-house algorithm

There are multiple benefits to using your in-house algorithm in XO:

• An in-house algorithm can utilize company-specific data that other algorithms might be restricted to use due to privacy concerns.
• Companies can build personalization strategies that are specific to their brand based on their own algorithms.
• A test and learn approach is available to the Data team, i.e. the data team can test multiple algorithms and strategies and make them directly available to the Merchandising team.

You can deploy and host your in-house algorithm in two different ways:

• Real-time models - You host and deploy your in-house algorithm.
• Not-in-real-time models - Crownpeak hosts and deploys your in-house algorithm.

Real-time models

Real-time models are your in-house algorithms that are hosted and deployed by yourself. Thus, the algorithm is called in real time. To host and deploy your in-house algorithm, you must develop an API that returns recommended items.

Hosting and deploying your in-house algorithm implies that your algorithm might initially not be able to take tags as input. Tags are an essential component of merchandising rules. Crownpeak can provide these tags by pushing them to your Google BigQuery environment. To do so, we require access to your Google BigQuery environment. For more information about hosting and deploying your in-house algorithm, contact our Customer Support team.

Not-in-real-time models

Not-in-real-time models are your in-house algorithms deployed by Crownpeak. In this case, you define with which frequency the algorithm is called. The Crownpeak team configures the requested frequency for you.

For Crownpeak to host and deploy your in-house algorithm you must share one or more pass-through files with us. Two options are available to you:

• Share files via an FTP
• Share files directly on GCS

Any pass-through file is a CSV model that describes item-to-item or user-to-item relationships, where the model defines several one-to-many-relationships. A source item or source user must be linked to N items that will be recommended when the model is to provide recommendations based on a given source item or user. Linked items can optionally include scoring.

An item is defined by its kind and ID. If an item is only defined by its ID, its kind is defaulted to “product”. 

Filenames should have the following format: <PREFIX>_YYYY-MM-DD.csv. The prefix is defined by yourself but should not be subject to change. If content is distributed among multiple files, filenames should have the following format: <PREFIX>_YYYY-MM-DD_<INDEX>.csv. The file(s) must not include a header and the separator must be a semi-colon.

Pass-through file without scores

If you intend to use merchandising rules based on filters, you must provide a pass-through file without scores.

A CSV model not including scores must have one of the two following formats depending on the source:

Recommended items are listed in order of proximity. Therefore, recommended items appear to the end-user in the same order as they are listed in the items_recommended column.

Pass-through file with scores

While including scores in your pass-through file is optional, some use cases require scoring:

• Using a Hybridization framework combining in-house and XO algorithms
• Weighting results based on custom scores
• Using merchandising rules based on boost and buries

A CSV model that includes scores must have one of the two following formats depending on the source:

Scores are a float between 0 and 1. The bigger the score, the closer the recommended item to the source item or user. Thus, items with higher scores appear first.

Setting up your in-house algorithm

Crownpeak performs the initial setup of your in-house algorithm in the XO Console. To do so, we require the following information:

• The name you wish your in-house algorithm to have which should be descriptive
• A short description of your in-house algorithm to help others understand the goal of this algorithm
• Optional: The host address if your in-house algorithm is hosted by yourself
• A timeout in milliseconds which defines the timespan after which an alternative algorithm will be called in a Fallback framework
• Whether Cache should be activated - Cache should not be activated if the algorithm is used for personalization as the results should be specific to every individual end-user.

Once Crownpeak has set up your in-house algorithm, you can provide more information about the algorithm in the XO Console. The following outlines best practices to ensure maximum clarity for Data team members:

• Open Algorithm Library in the XO Console.
  Algorithm > Algorithm Library

• Click on the newly created algorithm.
• Click Add a description to pass on valuable information about the algorithm.
• Under Definition & principles, click Define the principles to communicate to others how the algorithm can be used.
• Under Use cases, click Add a use case to keep record of when and where the algorithm can be used.

• Create strategy templates based on your algorithm.

Creating a strategy template

Each algorithm serves as the basis for one or multiple strategies. While only the Data team is concerned with algorithms, recommendation strategy templates are accessible to the Merchandising team to be configured and used in recommendation widgets.

The Data team is responsible for defining configuration elements for each strategy served by a given algorithm. A set of configuration elements describes a given strategy template. Merchandisers set the configuration parameters when usings the strategy in a recommendation widget.

To create a strategy:

• Open Algorithm Library in the XO Console.
  Algorithm > Algorithm Library
• Click + Add first strategy.
  Alternatively: Click on the menu button in the right corner of the algorithm box and choose Add a Strategy.

• In the Strategy name field in the Configuration panel, enter a strategy name.
  Ensure that your strategy name is descriptive and clearly communicates the intent of the strategy. This name will be visible to merchandisers.
• Optional:
  
  • Click the settings icon in the Configuration panel.
    → An Advanced configuration window opens.

• • Under General parameters, add the English and French version of the label.
  • In the Timeout field, add a strategy-specific timeout.
  • Activate Cache for the strategy.
  • Click Update configuration to save your changes.
    → You are redirected to the Configuration panel.
• Add Configuration elements, such as Items, using Drag & Drop to build a strategy template.

• Click Save strategy.
  → You are redirected to the Algorithm Library starting page.
• On the Algorithm Library starting page, click on your newly created strategy.
• Add a description in the text box to pass on valuable information about the strategy.
• Under Definition & principles, click Define the principles to communicate to others how the strategy can be used.
• Under Use cases, click Add a use case to keep record of when and where the strategy can be used.
• Activate your strategy using the toggle-switch in the top right-hand corner to make the strategy available to merchandisers.

Configuration elements

When creating a strategy template, configuration elements are used to define which values the merchandiser can configure when using said strategy in a recommendation widget. The strategy template determines the eventual output structure of the request sent to the algorithm during an API call.

A strategy template consists of one or more configuration elements. We differentiate between basic and XO-specific configuration elements. Each element consists of general and element specific attributes.

Basic configuration elements

The use of basic configuration elements is specific to use cases, the respective goal of a strategy, its inputs, and the expected input format.

• String
• Integer
• Float
• List
• Boolean
• Mixed
• Group of fields

General configuration element attributes

Each configuration element has at least the following required and optional attributes:

Constraints take the following additional attributes:

Display conditions take the following additional attributes:

XO-specific configuration elements

An XO-specific configuration element has general as well as additional attributes. The configuration element determines the format of the output sent to the API after configuration by the Merchandizing team. There are multiple types of XO specific configuration elements:

{
    fieldName: ['context1', 'context2']
}

{
    profile: {
        "id":"b2876e1b-5437-4d2b-92e5-ba79da6bcbc8",
        "datasources":{
            "582d85cd9fe7037e5cd76561":"2808187"
        }
    }
}

{
    fieldName: ['product#itemId', 'product#itemId'] // where "product" is an example of item kind
}

{ 
    fieldName: ['tag1','tag2'] 
}

{
    fieldName: ['attribute1', 'attribute2']
}

{
    fieldName: ['segment1', 'segment2']
}

{
    fieldName: ['verb1', 'verb2']
}

{
    datasources: [{
        "_id":"557715d773f49cd2c0de0267",
        "params" : {
           "trackerKey" : "557715c4d6166844c0bea7dd"
        },
        "provider" : "tracker",
        "name" : "Menlook IT - Tracker"
    }]
}

{
    fieldName: ['topVolume']
}

Strategy template example

To create a strategy template which results in a strategy that recommends items based on items viewed in a given context, add the following configuration elements and respective attributes:

• In the Configuration panel add a descriptive strategy name, e.g. “SimilarTo”.

-

Adding Items element

• Add the configuration element Items using Drag & Drop.
• Click on the newly added Items element to open the element configuration.

• In the Name field, add a name for your element, e.g. “similarItems”.
• By default, the element is Required. Do not change this setting.
• Select Allow variables.
• Add an element title in the Title field, e.g. “Related Items”.
• Add a description in the Description field, e.g. “The returned items must be similar to the selected items”.
• Click Return to element list.
  → You are redirected to the Configuration panel.

Adding Boolean element

• Add the configuration element Boolean.
• Click on the newly added Boolean element to open the element configuration.
• Add an element name, e.g. “randomize”.
• Unselect Required.
• Add a title, e.g. “Activate Randomization”.
• Add a description, e.g. “This will shuffle items with the closest ones, such that the returned items will be different on each call.”
• Click Return to element list.
  → You are redirected to the Configuration panel.

Adding Context element

• Add the configuration element Context.
• Click on the newly added Context element to open the element configuration.
• Add an element name, e.g. “context”.
• Unselect Required.
• Add a title, e.g. “Context”.
• Add a description, e.g. “This will retrieve the current context.”
• Click Return to element list.
  → You are redirected to the Configuration panel.

Adding Boolean element

• Add the configuration element Boolean.
• Click on the newly added Boolean element to open the element configuration.
• Add an element name, e.g. “isDiversified”.
• Unselect Required.
• Add a title, e.g. “Activate diversification”.
• Add a description, e.g. “This will diversify the retrieved items.”
• Click Return to element list.
  → You are redirected to the Configuration panel.

Adding Group of fields element

• Add the configuration element Group of fields.
• Click on the newly added Group of fields element to open the element configuration.
• Add an element name, e.g. “diversificationParameters”.
• Unselect Required.
• To add a Display condition, set Target to “isDiversified”, Operator to equal to, and select Value.
  →  Adding a Display condition ensures that the merchandiser can only see the input field for diversification parameters if the Boolean element “isDiversified” is set to “true”.
• Click Return to element list.
  → You are redirected to the Configuration panel.

Adding Attributes element to Group of fields

• Add the configuration element Attributes to the Group of fields element “diversificationParameters” using Drag & Drop.

• Click on the newly added Attributes element to open the element configuration.
• Add an element name, e.g. “attributes”.
• By default, the element is Required. Do not change this setting.
• Set Max attributes to 1.
  → This determines the number of attributes that can be selected by the merchandiser.
• Select Allow variables.
• Add a title, e.g. “Attributes used to diversify”.
• Add a description, e.g. “If possible, there will be no items with the same attribute value close together.”
• Click Return to element list.
  → You are redirected to the Configuration panel.

Adding Integer element to Group of fields

• Add the configuration element Integer to the Group of fields element “DiversificationParameters”.
• Click on the newly added Integer element to open the element configuration.
• Add an element name, e.g. ”cycleSize”.
• By default, the element is Required. Do not change this setting.
• Add a label, e.g. “cycleSize”.
• Add a description, e.g. “If possible, there will be no items with the same attribute values in this cycle size”.
• Click Save strategy.

Once you have saved and activated your strategy template, merchandisers may use it as part of a merchandising rule. After a merchandiser has filled in values for the elements defined above, i.e. created a strategy, an output for the above strategy, which is sent to the algorithm during an API call, could look as follows:

{
similarItems: ['product#12345','product#13424'],
randomize: false,
context: ['1554'],
isDiversified: true,
diversificationParameters: {
attributes: ['color'],
cycleSize: 4
}
}