Product Recommendation API

Product Recommendation API is a feature of Pricefx Core, which allows a user to add to a Quote some products from list of recommended products. This list is:

available via special button Add Recommended Products found on Quote Items page
produced by a Model in Optimization module.

Note: This specific core API solves only the special Add button on Quote Item page. If you need to implement the list of recommended products on the quote item, you will do it in the quote item logic, for example, by reading data from the Model (via the same Evaluation logic), or from Product Extension, or so.

Architecture

Figure 1. Schema of Product Recommendation API

Process

On the Quote Detail page, the user clicks on Add Recommended Products. This button is visible only when the Product Recommendation is switched on by the configuration.
The system calls the Model Evaluation method once for each category in the list. For each call of Evaluation:
1. The Evaluation will find the proper products for the given Category and return them back.
2. The Evaluation can also further filter the calculated product list by the Product Filter, which was created by the Quote Product Picker Filter Logic. This filter is provided to the Evaluation logic via input.productFilter.
The user interface will present the user a list of products from all categories to choose from.

Configuration

Configuration of the Product Recommendation feature for Quotes is stored in Advanced Configuration Option quoteProductRecommendationsConfig.

This property stores the link to the model with Product Recommendation data.

Example of Product Recommendation configuration in Advanced Configuration Option quoteProductRecommendationsConfig:

{
 "recommendationsEnabled": true,
 "modelName": "ProductRecModelName",
 "evaluationName": "ProductRecommendation_Eval",
 "elementName": "ProductRecommendation",
 "allowDuplicates": false,
 "categories": [
  {
   "categoryName": "customer",
   "defaultMaxResults": 20,
   "enabled": true
  },
  {
   "categoryName": "productHistory",
   "defaultMaxResults": 20,
   "enabled": true
  },
  {
  "categoryName": "customerSegment",
  "defaultMaxResults": 30,
  "enabled": true
  }
 ]
}

{
 "recommendationsEnabled": true,
 "modelName": "ProductRecModelName",
 "evaluationName": "ProductRecommendation_Eval",
 "elementName": "ProductRecommendation",
 "allowDuplicates": false,
 "categories": [
   {
   "categoryName": "frequentlyPurchased",
   "defaultMaxResults": 30,
   "enabled": true
 },
   {
   "categoryName": "boughtTogether",
   "defaultMaxResults": 30,
   "enabled": true
 },
   {
   "categoryName": "othersBuy",
   "defaultMaxResults": 30,
   "enabled": true
 },
   {
   "categoryName": "upSell",
   "defaultMaxResults": 30,
   "enabled": true
 },
   {
   "categoryName": "downSell",
   "defaultMaxResults": 30,
   "enabled": true
   },
   {
   "categoryName": "similarProducts",
   "defaultMaxResults": 30,
   "enabled": true
 },
   {
   "categoryName": "similarBrand",
   "defaultMaxResults": 30,
   "enabled": true
   }
 ]
}

JSON Schema of quoteProductRecommendationsConfig

recommendationsEnabled* - (boolean) When true, Product Recommendation is switched ON for all Quote Types. By default, it’s false.
modelName* - (text) Unique name of the Model, from which the product recommendation data should be read. When evaluationName is set, the modelName is expected to be the name of Model based on Model Class. When evaluationName is not set, the modelName is treated as name of Model of type Model Type.
evaluationName - (text) Unique name of Model’s Evaluation, which will be used to retrieve the data about recommendations. Use only when reading data from Model based on Model Class. When this value is not set, it’s an indication, that modelName refers to ModelType and not ModelClass.
elementName - (text) Name of the evaluation logic element, which provides the list of recommended products. Only for Model of type Model Class. See Model Evaluation Logic.
allowDuplicates - (boolean) Used by the endpoint (e.g. Quotes screen) to avoid the same product to appear as a result for different recommendation categories. The recommendation endpoint evaluates the recommendation model several times: one time for each category. As each recommendation categories may return the same product, the allowDuplicates is used by the endpoint to avoid or not a same product to appear as a result for different recommendation categories. By default, it’s false.
categories* - (list of objects) Recommendation categories are there to distinguish different source of recommendation, like recommendation based on product similarity, or recommendation based on clients similarity (this product is recommended as other clients buying one product buys also this other product). The recommendation endpoint evaluates the recommendation model several times: one time for each category. Each category has the following properties:
- categoryName* - (text) Name of the category. Must be unique within the list of categories. The category name will be passed to the evaluation logic. For list of valid options, see category names for Product Recommendation v1 or v2.
- enabled* - (boolean) If this category is enabled.
- defaultMaxResults - (integer) If the evaluation logic returns for given category more than #defaultMaxResults recommendations items, the list will be shorted by the system to the defaultMaxResults size.
- allowDuplicates - (boolean) Deprecated. It is here only for backwards compatibility. See allowDuplicates on the root level for description. If the allowDuplicates is set on the root level, then this value will be ignored.

Product Recommendation Model Class version

There are two major versions of Product Recommendation Model Class, v1 and v2, also known as PR1 and PR2. API is compatible with both versions, but they differ in names of categories, and this needs to be reflected in Advanced Configuration.

Product Recommendation v1 have categories named:

customer
productHistory
customerSegment

Product Recommendation v2 (since version 12.0) renamed existing categories and added new ones, having categories named:

frequentlyPurchased - formerly customer
boughtTogether - formerly productHistory
othersBuy - formerly customerSegment
upSell
downSell
similarProducts
similarBrand

Internationalization

When the names of the categories show up on the screen, they’re translated via specific translation keys:

Category Name	Translation Key

Category Name	Translation Key
customer	unity_qm_items_recommended_category_customer
customerSegment	unity_qm_items_recommended_category_customer_segment
productHistory	unity_qm_items_recommended_category_product_history
boughtTogether	unity_qm_items_recommended_category_bought_together
frequentlyPurchased	unity_qm_items_recommended_category_frequently_purchased
othersBuy	unity_qm_items_recommended_category_others_buy
upSell	unity_qm_items_recommended_category_up_sell
downSell	unity_qm_items_recommended_category_down_sell
similarProducts	unity_qm_items_recommended_category_similar_products
similarBrand	unity_qm_items_recommended_category_similar_brand