on - edited on by
Victor Chen
Introduction
The goal of this article is to provide detailed steps and explanation on how to create and use Result Improvement Rules (RIR) along with best practices to support a positive user experience. This example will be specific to the process of boosting content based on a user’s country matching that of the content being searched. This type of RIR does rely on the content being appropriately tagged with supporting country and language data.
Overview
This article will step through the configuration of RIR for both country and language. In this instance the boost process will be contained within a single rule to take advantage of minor performance gains as well as simplifying maintenance operations across the various boost actions. However, it is possible to split each component part into a separate RIR.
Details
When a result improvement rule with a boost action activates, AI Search modifies the relevancy scores for search results from an indexed source specified in the action. Boosting content will make modifications to the relevancy scores of items in a query’s search results. The set of search results does not change, but their ranking does. If multiple boost actions are triggered on the same result set the effect on the score will be additive, with each action further increasing the relevancy score on the result.
For example:
- Boost search result records that include field values matching a dynamically populated value from the user context.
- Boost search result records that include field values matching a static value that you specify.
Boost by Country Configuration
FYI
Observe the 'sys_user' table, the definition of the 'country' field has choices defined. Notice in that list the ‘Label’ and ‘Value’ are not the same. The label is the full country name, and the value is the alpha-2 country code. Within a RIR when the user’s country field is selected know that the ‘Value’ not the ‘Label’ is used in the comparison.
Prerequisite - string: Tagging content to support boosting on country
First create or confirm the existence of an appropriate field on the content. In this case the country's alpha-2 ISO code will be used. If it does not already exist create a new field ‘u_country_iso’ specify String as the column type in [kb_knowledge] table. This field will contain the ISO code of the country. Finally, populate the value of this field in [kb_knowledge] table with appropriate ISO codes.
Prerequisite - list
Create a new field named u_country_iso and specify List as the column type in the [kb_knowledge] table. This will contain ISO codes of the countries this article pertains to. Configure the Choices of the new u_country_iso field making sure that the Label and Value are the same.
Recommendation: add a ‘global’ choice to allow for boosting of content that is not specific to any country.
Populate u_country_iso on the content itself. This will require adding the new u_country_iso field to the KB article form.
Note: Using a ‘List’ field will require setting a system property details in KB1218966
Configuration:
To begin the configuration, navigate to All > AI Search > Search Experience > Search Profiles. Select the appropriate search profile, from the configuration section on the Result Improvement Rules tab select Create.
Create a new rule LangAndCountry and select Activate on all queries then save. This example will illustrate an evergreen rule with an End Date set out far into the future.
Select Create Boost Action to start the action definition. Boost Type: Boost By User Context (dynamic). Indexed Source: Knowledge Table. When: u_country_iso. Finally Matches the Searcher’s: Country. From there set the Boost Weight to 1000 as a starting point.
Note: The field u_country_iso is a new field added to the KB (Knowledge Base) article table as specified in the prerequisite section above
Optional ‘Global’ boost
If the ‘global’ value was added to the u_country_iso choice list an additional boost action can be created to apply the same boost value to that content as is being applied to the country specific content. Start by creating an additional boost action. Boost Type: Boost By Field Match (static). Indexed Source: Knowledge Table. When: u_country_iso. Finally Contains: global. From there set the Boost Weight to 1000 as a starting point.
Boost by Language Configuration
Prerequisite: Tagging content to support boosting on language
The existing Language field from the kb_knowledge table should be used. Be sure to populate this field on the content with the exact same values that are defined in the sys_user table for the field. Note that the preferred_language field is not directly accessible from the portal user preferences selection dialog. There is a KB article with further details and a workaround. Below is an example of choices defined in the sys_user table.
Next populate language on the content itself, making sure to match the value defined in the sys_user table exactly.
Configuration:
To begin the configuration, navigate to All > AI Search > Search Experience > Search Profiles. Select the appropriate search profile, from the configuration section on the Result Improvement Rules tab select the existing LangAndCountry Rule.
Select Create Boost Action to start the action definition. Boost type Boost By User Context (dynamic). Select the Indexed Source Knowledge Table. From the When dropdown select language. Finally Matches the Searcher’s select Language. From there set the Boost Weight to 1000 as a starting point.
Once the boost action has been created. Select Submit and update the rule itself and finally you will be able to publish the search profile with the newly updated Result Improvement Rules.
Validation
Country
Note: Prior to validation reindex the kb_knowledge table.
Using AI Search Preview found at All > AI Search > Preview > Search Preview. Test the new configuration, in the example above a kb article was updated to have DE and IT as country codes. Below are the results when the user country is set to US and then to DE. The change in search result order based on the score value verifies the boost has been applied.
Language
Using AI Search Preview found at All > AI Search > Preview > Search Preview. Test the new configuration, in this example a kb article was updated to have fr as the language. Below are the results when the user language is set to en and then fr. The change in search result order based on the score value verifies the boost has been applied.
Results for a French language user
Results for non-French language user
Best Practice
- For User Context based boost rules it must be an exact match on the field value
- Regarding the configuration of the country field on the KB table. Configuring that field as a list is supported however it can’t be configured as a reference field. For example, in the column definition “Choice List Specification” needs to be “—None—” and the Choices would need to be explicitly defined such that the Label and Value match the Alpha-2 country code exactly.
Further Reading
The Result improvement Rules are rules to boost, promote, or block search results for specific searches. You can also boost search results for documents matching elements of the user context, such as a user's location or device.
Result improvement rules with boost actions override the default search result order produced by the AI Search machine learning relevancy feature. Rules with block or promote actions override the default result set for a search query.
AI Search - Result Improvement Rules for Global Companies [AI Academy]
Hello @Shamus Mulhall ,
I have created a boost rule on user language on User context (dynamic). If KB article language matches users language boost those articles, however I get a warning on search preview. (both language have same values)
Any thoughts what's the error is about ? I have tried looking but didn't any. Thank you!
Boost rule:
Hi @Bharath38 search preview can be helpful but the properties settings can lead to confusion, our recommendation would be to test using the UI you are looking to update.
In your current situation I believe it is a result of not selecting the language option in the search preview context setting shown in the screenshot below.
Hello @Shamus Mulhall ,
Can you expand a bit explanation about the part of creating u_country_iso field?
Our country field on kb_knowledge is a string type field with associated a choice list referencing to sys user country field.
Does it works?
Also, the field MUST be called u_country_iso or there is no problem using a different one?
Then I would be also interested to understand what is exactly triggering the match between u_country_iso on kb_knowledge and sys_user country field?A scheduled job?A business rule?
I would love to understand how can I check which country value has been hit exactly when the Result Improvement rule is hit.
