45 Knowledge Search

If you are using Oracle Service Cloud Knowledge Foundation, then you can use the System.KnowledgeSearch built-in component to search for and display articles from that service.

Note:

Integration with Oracle Service Cloud Knowledge Foundation Version 19C and later is supported in Oracle Digital Assistant Version 20.08 and later.

To integrate your skill with a Knowledge Foundation interface, you:

  1. Add a knowledge search integration. You only need to do this once per Service Cloud interface.

  2. Add one or more System.KnowledgeSearch components to the skill's dialog flow, as described in Use the System.KnowledgeSearch Component.

Add a Knowledge Search Integration

To use the System.KnowledgeSearch component in a skill to search for and retrieve Oracle Service Cloud Knowledge Foundation articles, you must create a knowledge search integration for the Service Cloud interface.

Before you create a knowledge search integration for a Knowledge Foundation interface, confirm that your Oracle Service Cloud Account Manager has enabled the Connect Knowledge Foundation API at the site level and the II_CONNECT_ENABLED configuration setting is switched on. Otherwise, when you invoke the System.KnowledgeSearch component, it will return a global error because access is denied.

To create a knowledge search integration, complete these steps:

  1. In Oracle Digital Assistant, click Icon to open the side menu to open the side menu, select Settings, and then select Knowledge Services.

  2. In the Knowledge Search tab, click + Knowledge Search Integration

    The Create Knowledge Search Integration dialog displays.

    Description of knowledge-search-integration-create.png follows
    Description of the illustration knowledge-search-integration-create.png
  3. Provide this information:

    Field Required Description
    Name Y A unique name for the integration.
    Description N Description of the integration.
    Service Cloud Host Y The host name for the service. For example: rnow12345.example.com
    Service Cloud Interface Y The interface to use. For example: rnow12345 or rnow12345_2.

    Make sure that the answer access levels for the knowledge base answers that your skills will use are available for this interface.

    Service Cloud Version Y Indicate whether the version is 20A or later, or earlier than that.
    User Name Y

    The user name for a Service Cloud account. The user must be associated with a Service Cloud profile that has Public Knowledge Foundation API account authentication and session authentication permissions selected on the Profile Permissions Administration tab.

    The user must also have access to the articles that the skill needs to retrieve.

    Password Y The user's password.
  4. Click Create Knowledge Search Integration.

Use the System.KnowledgeSearch Component

You use the System.KnowledgeSearch component to search for and display information from a knowledge service.

Using this component, you specify the Knowledge Foundation to search, how many results to display, and whether to display the answer or the special response. You also can configure labels and prompts. For component property details and transitions, see System.KnowledgeSearch.

A common technique for knowledge search is to implement a roll-over search. If a user's utterance doesn't resolve to any intent within the skill's confidence threshold, then the skill searches the knowledge base using the utterance as the search term. For example, your knowledge base might contain articles about your return policy, shipping return costs, and whether one can return wearable products. Your skill could include intents that are specifically tailored to use precise knowledge base searches to return these answers. Should the user ask a related question that your skill doesn't specifically handle, such as a question about warranties, then the question would resolve to the unresolved intent and your skill could perform a knowledge base search with the user's question as the search term.

To implement this technique, do the following steps:

  1. Associate a set of related questions with a specific search term: For each knowledge base answer that you want to use in the skill, create an intent with a set of example utterances (training corpus). When the user utterance resolves to that intent, transition the dialog flow to a state that searches the knowledge base with a search term that returns the desired answer. The training corpus along with the natural language parser (NLP) help the skill resolve questions that are similar to the training corpus to that intent.

  2. Employ the user's utterance as the search term for unresolved intents: If the user utterance doesn't resolve to any intent within the skill' confidence level, then transition the dialog flow to a state that searches the foundation's knowledge base with the search term set to the user utterance. That is, perform a roll-over search.

Note that you must first create a knowledge search integration before you can use this component.

Associate Related Questions with a Search Term

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.

Description of kf-assoc-intent-term.png follows
Description of the illustration kf-assoc-intent-term.png

Tip:

This example uses the answer's summary for the search term. You also can use the answer's ID.

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 (the setSearchTerms state in the following example).

  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.)

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

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

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

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

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).
    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: ""
    transitions:
      return: "reset"

Employ User Utterance as Search Term

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.

This example shows how to set the searchTerm to the user's utterance:

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).
    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: ""
    transitions:
      return: "reset"

Knowledge Search Sample Skill

The Skill Store offers the sample Automated Agent Assistant digital assistant, which not only shows how to build a digital assistant that acts as an agent, but contains a sample framework for integrating with Oracle Service Cloud Knowledge Foundation.

To learn how to use this sample to build your own digital assistant that integrates with Oracle Service Cloud, see Automated Agent Assistant Sample.

How the System.KnowledgeSearch Component Displays in Oracle Service Cloud Chat

How the results from the System.KnowledgeSearch component appear depend on whether they are displayed in the default chat that's accessed through the customer portal or the Oracle Inlay Toolkit embedded chat inlay.

  • Links: Links appear as buttons in the embedded chat inlay. In the default chat, the label is dislayed as text, and it is followed by a clickable URL.
  • Multiple Results: When there is more than one result, the results appear as verticle cards in the embedded chat inlay. In the default chat, the results appear horizontally.

Note that images don't appear in the results.

This table illustrates how single and multiple results display in the embedded chat inlay and the default chat.

Example Component Configuration Embedded Chat Inlay Default Chat
Example of a single result:
    component: "System.KnowledgeSearch"
    properties:
      ...      
      resultSizeLimit: 1
      resultLinkLabel: "Show More"
      searchLinkLabel: "Search for Similar Answers"
      ...
Described in text Described in text
Example of multiple results:
    component: "System.KnowledgeSearch"
    properties:
      resultSizeLimit: 3 
      resultLinkLabel: "Show More"
      searchLinkLabel: "Open Page with All Answers"
      ...
Described in text Described in text

Oracle Service Cloud supports embedded chat inlay for versions 20A and later. To learn about the embedded chat inlay, see the Oracle Inlay Toolkit documentation.