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 named 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 (it's great if you can start with 12 to 24 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 state in the dialog 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 state and use a map context variable to associate your knowledge intents with search terms.

The following diagram illustrates how to implement the single-state method. 1) You use a map context variable to associate the knowledge intents with search terms. 2) You set each knowledge intent's action in the Intent state to transition to a data flow that uses the map to set the searchTerm context variable to the intent's search term. 3) You then transition to a state that searches the knowledge base for the searchTerm value.

Here are the detailed steps that you need to do for each knowledge intent:

1. Add the intent and search term to a context variable that associates intents with search terms as shown in this example.

   context:
     variables:
       iResult: "nlpresult"
       intentName: "string"
       searchTerm: "string"
       searchTerms: "map"    
   
   states:
   
     setSearchTerms:
       component: "System.SetVariable"
       properties:
         variable: "searchTerms"
         value:
           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?" # (1)
           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?"
       transitions:
         next: "intent"

2. In the intent state, add an action for the intent, and have the action transition to the start of a dialog flow that gets the search term for that intent. (For example, the knowledge.Product Registration: "startIntentKnowledgeSearch" action in the following code.)

   
     intent:
       component: "System.Intent"
       properties:
         variable: "iResult"
       transitions:
         actions:
           system.Greeting: "welcome"
           system.Unsatisfactory Response: "transferToAgent"
           system.Request Agent: "transferToAgent"
           knowledge.Shipping Return Costs: "startIntentKnowledgeSearch"
           knowledge.Locate Service Tag or Serial: "startIntentKnowledgeSearch"
           knowledge.Support Account: "startIntentKnowledgeSearch"
           knowledge.Product Registration: "startIntentKnowledgeSearch" # (2)
           knowledge.Noncontiguous Delivery Time: "startIntentKnowledgeSearch"
           knowledge.Return Policy: "startIntentKnowledgeSearch"
           unresolvedIntent: "genericKnowledgeSearch"

3. After setting the searchTerm variable as shown here, transition to a System.KnowledgeSearch state that uses the search term value for the component's searchTerm property (knowledgeSearchForGivenSearchTerm in the following example).

   
     startIntentKnowledgeSearch: # (2)
       component: "System.ResetVariables"
       properties:
         variableList: "searchTerm, intentName"
       transitions:
         next: "setIntentName"
         
     setIntentName:     
       component: "System.SetVariable"
       properties:
         variable: "intentName"
         value: "${iResult.value.intentMatches.summary[0].intent}"
       transitions:
         next: "setSearchTerm"      
   
     setSearchTerm:
       component: "System.SetVariable"
       properties:
         variable: "searchTerm"
         value: "${searchTerms.value[intentName.value]}"
       transitions:
         next: "knowledgeSearchForGivenSearchTerm" # (3)     

4. In the System.KnowledgeSearch state, set the searchServiceName to the name of the knowledge search service that you created in Settings and set the searchTerm to the value of the searchTerm that you set in the previous step..

   
     knowledgeSearchForGivenSearchTerm:   
       component: "System.KnowledgeSearch"
       properties:
         # Set to the name of the search service that is configured in Settings
         searchServiceName: "KnowledgeSearch"
         searchTerm: "${searchTerm.value}" # put the search term here (3)
         # searchPrelude: Optional property. If missing, there's no search prelude.      
         resultSizeLimit: 1 # Change to how many articles to show. 
         # resultVersion: Optional property. Defaults to "Answer".
         # resultVersionExclusive: Optional property. Defaults to false.
         resultLinkLabel: "Show More"
         # defaultAttachmentLabel: Optional property. Defaults to "Download"
         searchLinkLabel: "Search for Similar Answers"
         noResultText: >
           I don't have an answer for that. Try rephrasing your question 
           (or you can ask to speak to a live agent).
         # cardLayout: Optional property. Defaults to "horizontal"
       transitions:
         actions:
           resultSent: "offerMoreHelp"
           noResult: "reset"
           serverError: "handleSearchServerProblem"
         error: "handleSearchError"
         next: "reset"    

5. Add the states for the actions, error, and next transitions. The full dialog below shows some examples for these states.

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

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

Here's an example of the full dialog flow.

context:
  variables:
    iResult: "nlpresult"
    intentName: "string"
    searchTerm: "string"
    searchTerms: "map"
    someVariable: "string" # For the reset state

states:

  #
  # Set search term for each knowledge intent
  #

  setSearchTerms:
    component: "System.SetVariable"
    properties:
      variable: "searchTerms"
      value:
        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?" # (1)
        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?"
    transitions:
      next: "intent"
  
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        system.Greeting: "welcome"
        system.Unsatisfactory Response: "transferToAgent"
        system.Request Agent: "transferToAgent"
        knowledge.Shipping Return Costs: "startIntentKnowledgeSearch"
        knowledge.Locate Service Tag or Serial: "startIntentKnowledgeSearch"
        knowledge.Support Account: "startIntentKnowledgeSearch"
        knowledge.Product Registration: "startIntentKnowledgeSearch" # (2)
        knowledge.Noncontiguous Delivery Time: "startIntentKnowledgeSearch"
        knowledge.Return Policy: "startIntentKnowledgeSearch"
        unresolvedIntent: "genericKnowledgeSearch"

  #
  # Start knowledge search for a knowledge intent's search term
  # based on searchTerms context variable
  # 
  # First, reset variables
  #
  
  startIntentKnowledgeSearch: # (2)
    component: "System.ResetVariables"
    properties:
      variableList: "searchTerm, intentName"
    transitions:
      next: "setIntentName"
      
  # 
  # Set the intentName context variable
  #
  
  setIntentName:     
    component: "System.SetVariable"
    properties:
      variable: "intentName"
      value: "${iResult.value.intentMatches.summary[0].intent}"
    transitions:
      next: "setSearchTerm"      
    
  # 
  # Get the search term to use for the intent
  #
  
  setSearchTerm:
    component: "System.SetVariable"
    properties:
      variable: "searchTerm"
      value: "${searchTerms.value[intentName.value]}"
    transitions:
      next: "knowledgeSearchForGivenSearchTerm" # (3)            
      
  # 
  # This state searches for the searchTerm variable's value
  #
  
  knowledgeSearchForGivenSearchTerm:   
    component: "System.KnowledgeSearch"
    properties:
      # Set to the name of the search service that is configured in Settings
      searchServiceName: "KnowledgeSearch"
      searchTerm: "${searchTerm.value}" # put the search term here (3)
      # searchPrelude: Optional property. If missing, there's no search prelude.      
      resultSizeLimit: 1 # Change to how many articles to show. 
      # resultVersion: Optional property. Defaults to "Answer".
      # resultVersionExclusive: Optional property. Defaults to false.
      resultLinkLabel: "Show More"
      # defaultAttachmentLabel: Optional property. Defaults to "Download"
      searchLinkLabel: "Search for Similar Answers"
      noResultText: >
        I don't have an answer for that. Try rephrasing your question 
        (or you can ask to speak to a live agent).
      # cardLayout: Optional property. Defaults to "horizontal"
    transitions:
      actions:
        resultSent: "offerMoreHelp"
        noResult: "reset"
        serverError: "handleSearchServerProblem"
      error: "handleSearchError"
      next: "reset"    

  #
  # This state is called after knowledge search returns its results.
  #
  
  offerMoreHelp:
    component: "System.Output"
    properties:
      text: > 
        You can ask me another question if there's something 
        else that I can help you with.
    transitions:
      return: "offerMoreHelp"

  #
  # This state is called when there's a problem accessing the knowledge base such
  # as a server error fault or an unexpected error fault. When this error occurs,
  # the error message is stored in system.state.<state-name>.serverError.message. 
  # 
  
  handleSearchServerProblem:
    component: "System.Output"
    properties:
      text: >
        I'm not able to get an answer for that question. Let me know 
        if there's anything else I can help you with.
    transitions:
      return: "handleSearchServerProblem"      
  
  #
  # This state is called when there's a problem using the knowledge search component
  # such as when there's a problem with the knowledge search integration configuration
  # 
  
  handleSearchError:
    component: "System.Output"
    properties:
      text: >
        Oops, my answer mechanism for that isn't working properly.
        You can ask a different question or ask to speak to an agent?
    transitions:
      return: "handleSearchError"      

  #
  # This state ends the conversation
  #
  
  reset:
    component: "System.SetVariable"
    properties:
      variable: "someVariable"
      value: "x"
    transitions:
      return: "reset"

Tip:

The default values for the defaultAttachmentLabel, noResultText, and resultLinkLabel properties are stored in the skill's resource bundle. To change a default, open the skill's Resources Bundle page, click , 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.

A common use for the System.KnowledgeSearch 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, then use the component to search the knowledge base with the searchTerm 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.

The following example shows how to set the searchTerm to the user's utterance in a YAML dialog skill. For a visual dialog skill, you use skill.system.nlpresult.value.query instead.

context:
  variables:
    iResult: "nlpresult"
    someVariable: "string" # For the reset state

states:

  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        system.Greeting: "welcome"
        system.Unsatisfactory Response: "transferToAgent"
        ...
        unresolvedIntent: "genericKnowledgeSearch"
  
  #
  # This state searches the knowledge base with the user input as the search term.
  #

  genericKnowledgeSearch: 
    component: "System.KnowledgeSearch"
    properties:
      # Set to the name of the search service that is configured in Settings
      searchServiceName: "KnowledgeSearch"
      searchTerm: "${iResult.value.query}"
      searchPrelude: "I don't know the answer offhand. Let's see what articles we have..."      
      resultSizeLimit: 3 # Change to how many articles to show. Defaults to 10.
      # resultVersion: Optional property. Defaults to "Answer".
      # resultVersionExclusive: Optional property. Defaults to false.
      resultLinkLabel: "Show More"
      # defaultAttachmentLabel: Optional property. Defaults to "Download"
      searchLinkLabel: "Open Page with All Answers"
      noResultText: >
        I couldn't find any articles about that. Try rephrasing your 
        question (or you can ask to speak to a live agent).
      # cardLayout: Optional property. Defaults to "horizontal"
    transitions:
      actions:
        resultSent: "offerMoreHelp"
        noResult: "reset"
        serverError: "handleSearchServerProblem"
      error: "handleSearchError"
      next: "reset"

  #
  # This state is called after knowledge search returns its results.
  #
  
  offerMoreHelp:
    component: "System.Output"
    properties:
      text: > 
        You can ask me another question if there's something 
        else that I can help you with.
    transitions:
      return: "offerMoreHelp"

  #
  # This state is called when there's a problem accessing the knowledge base such
  # as a server error fault or an unexpected error fault. When this error occurs,
  # the error message is stored in system.state.<state-name>.serverError.message. 
  # 
  
  handleSearchServerProblem:
    component: "System.Output"
    properties:
      text: >
        I'm not able to get an answer for that question. Let me know 
        if there's anything else I can help you with.
    transitions:
      return: "handleSearchServerProblem"      
  
  #
  # This state is called when there's a problem using the knowledge search component
  # such as when there's a problem with the knowledge search integration configuration
  # 
  
  handleSearchError:
    component: "System.Output"
    properties:
      text: >
        Oops, my answer mechanism for that isn't working properly.
        You can ask a different question or ask to speak to an agent?
    transitions:
      return: "handleSearchError"      

  #
  # This state ends the conversation
  #
  
  reset:
    component: "System.SetVariable"
    properties:
      variable: "someVariable"
      value: "x"
    transitions:
      return: "reset"

Note that this example handles unresolved intents within a skill. When the flow navigates through the digital assistant's unresolved intent, then the request doesn't go through the skill's System.Intent component and the utterance won't be in ${iResult.value.query}. In this case, consider creating a state that uses ${system.message.messagePayload.text} for the search string. Then open the Digital Assistant and, in the Settings > Configurations page, go to Skill State Mappings and set the Digital Assistant Custom UnresolvedIntent Skill and Digital Assistant Custom UnresolvedIntent State to point to this state.

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 key/value pair word_connector: "AND" to the customProperties property in the System.KnowledgeSearch component as shown below:

  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 System.KnowledgeSearch 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, include the customFilters property. Add product and category items as needed to specify the product or category filter. You can have only one product filter and only one category 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 System.KnowledgeSearch component's resultVersion property to "Special Response" and set resultVersionExclusive 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 System.KnowledgeSearch 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 resultLinkLabel property to an empty string ("").

If the skill uses Visual Designer mode, this is the Web Article Link Label field. To set it to an empty string, use the FreeMarker literal notation ${r""}.

If you choose to display the full answer, you should try to limit the answer to just a few screen-fulls of text. Otherwise the user might have difficulty reading the text in a regular-sized chat widget.

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 locale property (for visual dialog skills, this is the Search Using 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 System.KnowledgeSearch 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 locale property for YAML dialog and the Search Using Locale property for visual dialog). 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 System.KnowledgeSearch 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 add the locale property and set it to the desired locale. Note that if none of the interfaces support the locale, then the component searches the default interface.

   For an dialog flow examples, see Associate Related Questions with a Search Term and Employ User Utterance as Search Term.