Product Rank for Catalog Search
This page describes how to configure and manage the product priorities (rank) in order to manipulate the order of the products displayed in the catalog search result.
Product Rank Concept
The products listed in the result of the catalog navigation are sorted in a certain order:
- By default in lexicographical order
- Through product rank
Default Order
Products are sorted lexicographically by default.
Product Ranking
One business requirement is to be able to modify the order of products to promote the prioritized product sales. This is what the product rank concept does.
The aim is to allow customers to set the order of the products according to their needs.
📌 Through the product rank, the customer can control the way products are displayed by prioritizing or deprioritizing some products.
Products that have the same product rank are sorted lexicographically by using the name of the product.
Product Rank Applied Scope
The product rank can be used everytime a catalog search is performed.
This includes, as illustrated below:
- First level searches in the Catalog on Cabinets, Dining, Openings, etc.
- Sub-level searches in the sub-catalog on Base Cabinet, Cooktops, etc.
- The filter functionality in the catalog browser
- The Replace button for the product.
The customer has the flexibility to activate product rank or not. For example, if s/he wants to limit the product ranking to the sub-catalog search level, this will be enabled by configuring the corresponding parameter defined in the Application Distribution.
➡ See below Configure Application Distribution Parameters for more information.
For textual search, product rank is not applied. The result of textual search presents the products regardless of the priorities set by the client.
For the Replace function in the catalog browser, the product ranking functionality is always enabled.
Product Ranking in Content Publisher
This section explains how to define and manage the product priority that will be applied in product ranking for the content publisher.
searchScore Property
There is a property for the product named "searchScore" that represents the priority of the product in search results and that is used to sort the products when applying product ranking.
❗ Each product has only one searchScore value.
This value will always be the same for a particular product in all the lists where this product appears. It means that the product will have the same priority in all sub-categories where it belongs to.
| Key | Type | Value | Description |
|---|---|---|---|
searchScore | integer | negative / 0 / positive | 0: new product with no specified value, not prioritized products, deprioritized products. negative: low priority. positive: high priority. |
The highest the score value is, the highest is the rank. Set a positive value to make products appear in the top of the list; conversely, set a negative value to put it in the bottom of the list.
Example
Below is an example for 9 products.
| Rank in the search results | searchScore |
|---|---|
| Top | 4 |
| Highest | 3 |
| Higher | 2 |
| High | 1 |
| No priority | 0 |
| Low | -1 |
| Lower | -2 |
| Lowest | -3 |
| Bottom | -4 |
📌 searchScore values are not limited.
Override searchScore via the API
The user is allowed to override a product according to their needs.
For example, s/he may want to have different priorities for the same product depending on the Retail Units.
| Retail unit | Search | Product | Rank |
|---|---|---|---|
| RetailUnit1 | Sub-catalog Base Cabinet | BaseCabinet1 | Top |
| RetailUnit2 | Sub-catalog Base Cabinet | BaseCabinet1 | Low |
To achieve different "searchScore" for a product in different retail units, the user needs to override the searchScore.
Because searchScore is a property of the product data model, you can retrieve and manage searchScore by calling the API.
➡ See the API documentation 🔗 for detailed information.
Retrieve a Product and its Value
To retrieve the value of searchScore, you can call the following endpoints:
To retrieve a specific product call GET /products/{id}
The searchScore is returned as illustrated below:
To retrieve all the products and their searchScore, call GET /products.
To retrieve products that match filter criteria, call GET /products/_filter.
Create or Update a Value
To set or update the value of searchScore, you can call the following endpoints:
PUT /products/{id}
POST /products/{id}
POST /products
PUT /contribution/products/{id}
For example, to modify the searchScore value of a particular product, you can use POST/products/{id}, as illustrated below.
📌 The update of value searchScore will take some time to affect search results because the backend search engine needs time to update (up to several minutes).
If you check the order of the products in the planner immediately after changing the searchScore value, the product priority may be unchanged; wait a few minutes until the update is performed.
Configure Application Distribution Parameters
This section explains how to configure the application distribution parameters in order to activate the product ranking and manage the locale used for lexicographic sorting.
productRank Parameter
Product searchScore can be taken into account or not at catalog level and at sub-catalog level.
A parameter named productRank is defined to indicate that the searchScore must be used when sorting products.
This parameter can be managed through the application distribution parameter catalogEntries 🔗.
| Key | Type | Default value | Description |
|---|---|---|---|
productRank | boolean | false | Activates product ranking if true. By default, the value is false if not specified. |
❗ The productRank parameter is not inherited from a parent category. You need to define its value precisely.
In the example above, the productRank parameter is set to true at sub-catalog level only. This means that when clicking the sub-category "Base Cabinet", the product will be sorted in the order defined by the client using searchScore. However, when clicking the category "Cabinets", the product rank will not be applied.
If you want to activate the product ranking on catalog level, you need to set the productRank to true at catalog level as illustrated below.
searchSortLocale Parameter
By default, the products are sorted by lexicographical order in catalog and sub-catalog search taking the product names into account.
❗ In a multi-language context, it is important to identify the sorting language because every language has its own sort order.
Therefore, we define a parameter called searchSortLocale to indicate the sorted language/locale that will be applied.
For example, in a planner where the locale is French, you can set searchSortLocale value either to sort lexicographically by using the same alphabet (i.e. French in our example) or a different alphabet (e.g. the Swedish alphabet).
➡ Both
localeandsearchSortLocaleare defined in the application distribution 🔗.
The 3DVia Documentation – March 2020