While it's possible to simply employ the user's utterance as the search term for a knowledge base search, it's often preferable to leverage the intent and natural language parsing features to ensure that the skill displays the best possible answer for a given question.

By creating an intent for each knowledge base answer that you want to incorporate into your skill, you can use the intent's example utterances (training corpus) to associate various questions with that answer. Using the training corpus, the natural language parser (NLP) will resolve other questions that are similar to the ones in the training corpus to that intent. As your skill is put to use, you can insights and retraining to improve the resolution of utterances to that intent.

When an utterance resolves to one of your intents, which we'll call knowledge intents, transition the dialog flow to a state that searches the knowledge base using a search term that will retrieve and display the desired answer.

As an example, let's say that you have a knowledge base answer about product registration that not only explains how to register a product, but describes the advantages of registering as well as how to update and retire a product. You would start by creating an intent for it (lets call it knowledge.Product Registration). You would then add several example utterances to the intent that illustrate the ways in which people would ask about product registration (you should start with a few dozen examples). Here's a small set of the example utterances you might use for knowledge.Product Registration.

• how to register my product
• I need to retire a registered product
• I want to update registered device
• is product registration important
• what are the advantages to registering a device
• why should we register products

Next, you would need to create a flow to search the knowledge base using a search term that will produce the desired answer. You can either create a knowledge search state for each knowledge intent and hard code the search term, or you can create a single flow and use a map variable to associate your knowledge intents with search terms.

Here are the steps to create a single flow in the Visual Flow Designer for all of the intents that are mapped to a specific search term:

1. In the Main Flow, create a global variable of type map to associate the knowledge intents with search terms. In this example, we'll call it searchTerms. Here's an example value that you could assign to such a variable if you have six intents:

   {
     "knowledge.Shipping Return Costs" : "Shipping Return Costs",
     "knowledge.Locate Service Tag or Serial" : "Locating Your Service Tag or Asset Serial Number",
     "knowledge.Support Account" : "My Support Account",
     "knowledge.Product Registration" : "How do I register my product?",
     "knowledge.Noncontiguous Delivery Time" : "What is the delivery time to Alaska, Hawaii and the U.S. Territories?",
     "knowledge.Return Policy" : "What is your return policy?"
   }

   Tip:

   This example uses the answer's summary for the search term. With Oracle B2C Service Knowledge Foundation, you also can use the answer's ID.
2. Start the flow with a Set Variable component and create a variable to hold the intent name (e.g. intentName) and enter the following FreeMarker expression as its value:

   ${skill.system.nlpresult.value.intentMatches.summary[0].intent}

3. After the Set Variable component you have just added, add another Set Variable component for the search term (e.g. searchTerm) and enter the following FreeMarker expression as its value:

   ${searchTerms.value[intentName.value]}

   This expression uses the searchTerms map you defined earlier to determine the search term based on the resolved intent.

4. After the second Set Variable component, add a Knowledge Search component and set its to Term to Search For property to ${searchTerm.value}".

5. In the Knowledge Search component state, set the Search Service Name to the name of the knowledge search service.

6. After the Knowledge Search component, add the states for the actions, error, and next transitions.

7. Click Validate to ensure that the dialog flow doesn't have any errors.

8. Click Train to train the skill with your example utterances.

9. On the Intents page for the skill, map each of the intents associated with a search term to this flow.

Tip:

The default values for the Text to Display Ahead of Results, Web Article Link Label, and Web Search Page Link Label properties are stored in the skill's resource bundle. To change a default, open the skill's Resources Bundle page by clicking, select the Configuration tab, and change the message for the KnowledgeSearch - <property name> key. If you use the skill's resource bundle to change the default, then you don't need to include the property in the component unless you want to override the default.

For an example YAML-based dialog flow using this technique, see Example: Associate Related Questions with a Search Term in a YAML Dialog Flow.

A common use for the Knowledge Search dialog flow component is to try and resolve a user's question or request that your skill wasn't designed to handle. If a user's utterance doesn't resolve to any intents, you can use the component to search the knowledge base with the Term to Search For property set to the user utterance. If it doesn't find any results, or if the user doesn't find the results helpful, you can offer other options such as transferring to a live agent or rephrasing the question.

You do so by setting the component's Term to Search For property to ${skill.system.nlpresult.value.query} (which is the expression to retrieve the user's utterance).

In YAML-based dialog flows, you use the searchTerm property and set it to ${iResult.value.query}. For sample YAML code, see Example: Employ User Utterance as Search Term.

By default, Oracle B2C Service Knowledge Foundation searches for answers that contain any of the words in the search term. If you want the search to return only the answers that contain every word in the search term, add the following key/value pair to the Custom Properties property in the Knowledge Search dialog flow component:

word_connector: "AND"

If your dialog flow is in YAML mode, the code would look something like this:

  startSearch:
    component: "System.KnowledgeSearch"  
    properties:
      searchServiceName: "KnowledgeSearch"
      searchTerm: "${searchTerm.value}"
      customProperties:
        word_connector: "AND"
    transitions:
      actions:
        resultSent: "offerMoreHelp"
        noResult: "reset"
        serverError: "handleSearchServerProblem"
      error: "handleSearchError"
      next: "reset"

You can have the Knowledge Search dialog flow component return only the search results for a specified product or category (or both).

To limit the results to those related to a product or category, use the Result Filters property. Add Product, Category, and Stripe Code items as needed to define the filter. You can have only one of each type of filter.

      customFilters:
        - name: "product"
          value: "heart rate monitor"
        - name: "category"
          value: "returns"

Oracle B2C Service Knowledge Foundation answers are typically written for web pages and thus can be too long to fully display in a conversation. For lengthy answers, the output is truncated and the user must click the Show More button to see the full content. When your answer is longer than a short paragraph, consider adding a special response that you tailor specifically for chat conversations.

To display the special response instead of the answer, set the Knowledge Search component's Preferred Version of Results property to Special Response and set Only Show Preferred Version to false. With these settings, the component outputs the special response if it exists. Otherwise it outputs the full answer if the result-size limit hasn't been met.

The following screenshots show the difference between a full answer and a special response. The first screenshot shows the full answer. Notice how the response to "how do I register a product", which begins with "Did you know that product registration is very important", is not the way a human would respond to the question, and thus is not "conversational." In addition, the full answer is cut off in the middle of the third paragraph. The second screenshot shows the special response, which is more conversational and not truncated.

To learn about adding special responses, see HTML Editor for Answers in Using B2C Service.

By default, the Knowledge Search dialog flow component just displays the first few lines of the answer along with a button that the user clicks to see the full answer in a browser tab.

If you want it to show all the answer's content, set the Knowledge Search component's Web Article Link Label to On and set the value of the systemComponent_KnowledgeSearch_resultLinkLabel resource bundle key to the FreeMarker literal notation ${r""}.

If your skill is in YAML dialog mode, you accomplish this by setting the System.KnowledgeSearch's resultLinkLabel property to an empty string ("").

Both Oracle Fusion Service Knowledge Management and Oracle B2C Service Knowledge Foundation support returning results for a specified locale.

For Oracle Fusion Service Knowledge Management, the search automatically returns the articles that are associated with the locale identified by profile.locale. You can override this by setting the component's Search Using Locale property (for YAML dialog mode skills, this is the locale property). If matching articles don't exist for the locale, it returns noResult.

For Oracle B2C Service Knowledge Foundation, the service must have separate interfaces for different locales, and you must configure the Knowledge Search integration to connect with the desired interfaces. When the Knowledge Search dialog flow component is invoked by a skill, it performs the search on the interface for which the locale matches the skill's profile.locale value. You can override this by setting the component's Search Using Locale property (for YAML dialog mode skills, this is the locale property). If there isn't a match, it uses the Knowledge Search integration's default interface.

Here are the steps to create a multi-language Oracle B2C Service Knowledge Foundation search skill:

1. Add a Knowledge Search Service integration for the main interface. Then add to the integration the locales for the other interfaces that you want the skill to search, and specify the default locale. Note that the profile of the user that you specify for the service integration must enable access for the interfaces.

2. Create a multi-language skill using one of these options:

   • Create a skill with native language support and use resource bundles to create the conversational text for each language that you want to support as described in Native Language Support for Skills

   • Create a skill that designates English as the primary language and use translation mode as described in Create a Multi-Language Skill Without Resource Bundles for Each Language.

3. Add the Knowledge Search component to the dialog flow. If you don't want the component to use the profile.locale value to determine which interface to search, then set the Search Using Locale property to the desired locale. If none of the interfaces support the locale, then the component searches the default interface.