Oracle by Example brandingOptimize Insights Reports with Conversation Markers

section 0Before You Begin

Background

This 30-minute tutorial shows you how conversation markers make the skill-level Insights reports easier read. In this tutorial, you'll explore the following use cases:

  • You want the various subflows, or intent-specific execution paths in the dialog flow definition, reported separately.
  • You want to limit the reporting to certain states in the dialog flow. Consequently, you want to exclude the states you consider extraneous from the Insights reports.

What Do You Need?

  • To complete this lab, you need an instance of Oracle Digital Assistant (ODA), Release 20.4 or higher.
  • The starter skill for this tutorial, which you can download here.

section 1Get Acquainted with Insights Reports

Before you change the Insights reporting by adding conversation markers to the dialog flow definition, let's first take a quick tour of a skill-level Insights, starting with the Overview dashboard. The Overview report gives you an at-a-glance view of how your skill has been performing. We're not going to delve into all aspects of the report, but here are some highlights:

  • Conversation Trends: This multiple line chart compares the number of completed, incomplete, and in-progress conversations for the selected time period.
  • Conversations: The Conversations section displays separate tallies for complete, incomplete, and in-progress conversations. It also displays the most-used channels.
  • Intents: Ranks the intent resolution using a stacked bar chart. Each bar represents one of the skill's intents. The bars themselves are segmented by the number of complete and incomplete conversations.
    • Description of this illustration follows
    Description of the illustration.

section 2Create the Skill

We’ll start by importing the InsightsDemo_starter skill

  1. Log into Oracle Digital Assistant.
  2. Click the menu icon in the top left corner to open the side menu
  3. Expand Development and then click Skills.
  4. Click Import Skill in the upper right and select the InsightsDemo_starter file. If you receive an error message saying that the bot already exists, it means that someone has already imported the skills and you can skip to the next step.
  5. Return to the Skills landing page by clicking Skills in the left navigation menu.
  6. Locate the InsightsDemo_starter file.
  7. Within the tile for InsightsDemo_starter skill, click the Options menu icon and then select Clone.
  8.  Name the clone <Your Initials>_InsightsDemo_starter. (For example: DSM_ InsightsDemo_starter.)
    9. Description of this illustration follows
    Description of the illustration.

section 3Set Up the Skill

  1. Open the skill.
  2. Take a look at its intents.
    3. Description of this illustration follows
    Description of the illustration.
  3. Click Settings The Settings icon.
  4.  In the General tab, make sure that Insights Enabled is switched on.
    5. Description of this illustration follows
    Description of the illustration.
  5. Click Train, choose Trainer Tm, then click Submit.
  6. Click Validate to make sure that the the dialog flow has no errors.

section 4Separate Conversations Reporting by Intents or Transitions

In this section, we're going to update the ShowMenu state in the dialog flow to log the different user interactions or requests that occur within the same chat session as different conversations. But before we get to that, let's take a look at the OBotML, have an initial chat, and then find out how it's reported in Insights.

Take a Look at the showMenu State

  1. Click Flows The Flows icon in the left navbar.
  2. In the dialog flow definition, locate the showMenu state. In particular note its transitions: 
    transitions:
      actions:
        pizza: "orderPizza"
        pasta: "orderPasta"
        textReceived: "intent"
    These transitions enable the dialog flow to branch at this state, which is the execution path for the ShowMenu intent. After the Dialog Engine moves to this state, users might choose to do something more than view the menu options. They can continue their order because of the orderPizza and orderPasta transition actions, or because of the textReceived transition action that resolves user messages to the other intents defined for the skill, OrderPasta and OrderPizza.

View the showMenu Intent Reporting

In this step, we'll see how the Conversations report records a conversation that's routed to the showMenu state.

  1. Click Skill tester icon (located at the top right) to open the Skill Tester.
    2. Description of this image follows
    Description of the illustration follows.
  2. Enter show menu, then click Send.
  3. After the skill replies with the Pizzas or Pastas message, enter I want pasta.
    4. Description of this illustration follows
    Description of the illustration.
  4. Click The Close icon to close the Skill Tester.
  5. Click Insights The Insights icon in the left navbar (if it isn't already open) and then click Conversations.
  6. In the Conversation report, notice that ShowMenu is the intent that was resolved for the entire conversation. This only tells part of the story. For a business user who wants to see separate transactions for pizza and pasta orders, this isn't enough.
    7. Description of this illustration follows
    Description of the illustration.
  7. Click Overview. If this is your first chat, there will one conversation recorded and showMenu will be the only entry in the Intents bar chart.
    8. Description of this illustration follows
    Description of the illustration.

Add Conversations Markers to the showMenu State

To enable the Insights to create a precise report of the interaction, you're going to add the insightsEndConversation: true conversation marker to the showMenu state:

  1. Click Flows The Flows icon in the left navbar.
  2. In the showMenu state, add the insightsEndConversation: true conversation marker under properties: 
    ShowMenu:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      insightsEndConversation: true
  3. Click Validate to check for errors (particularly ones involving indentation -- the conversation marker should be six spaces from the left margin).

View the Updated Report

Because of the addition of the insightsEndConversation: true property, Insights now considers any further interaction enabled by the orderPizza, OrderPasta, or textReceived transitions as a separate conversation. Let's test that out.

  1. Click Skill tester icon to open the Skill Tester.
  2. Click Reset to clear your input.
    3. The Reset button
  3. Enter show menu.
  4. Enter I want pasta.
  5. Click Close The Close icon to close the Skill Tester.
  6. Open the Conversations report. There are now two separate conversations: one for the ShowMenu intent and another for the OrderPasta intent.
    7. Description of this illustration follows
    Description of the illustration.
  7. Click the Overview tab. Because these intents are logged as separate conversations, the total number of conversations has been incremented by two rather than one. The OrderPasta intent has also been added to the Intents chart.
    8. Description of this illustration follows
    Description of the illustration.

Take a Look at the handleProblems State

In this section, we're going to take a look at the agent handover enabled by the skill's HandleProblems intent and initiated through the handleProblems state, the first stop in this intent's execution path. Configured as an action list, this state's speakToAgent and StartOver transitions fork the execution path:

#################
# Handle problems
#################
  handleProblems:
    component: "System.List"
    properties:
      prompt: "I don't seem to be able to help you. Would you like to speak with someone?"
      options:
      - label: "Yes, I want to speak with someone"
        value: "SpeakToAgent"
      - label: "No, let's start over"
        value: "StartOver"
      autoNumberPostbackActions: true
    transitions:
      actions:
        SpeakToAgent: "setupProfileFirstName"
        StartOver: "startOver"

Review the Reporting for the Agent Handover Action

Now let's see HandleProblems execution path in action and find out how it's reported in the Conversations report.

  1. Click The Skill Tester icon to open the Skill Tester.
  2. Click Reset.
  3. Enter I have a problem.
  4. Choose 1. Yes, I want to speak with someone.  Because the skill is not integrated with Oracle Service Cloud for this tutorial, it may return an "Error transferring to agent.." message. Ignore it.
    5. Description of this illustration follows
    Description of the illustration.
  5. Close the Skill Tester.
  6. Open the Conversations report and then click Refresh The Refresh icon to ensure that the report is updated. The report notes the HandleProblems as the intent for the entire conversation.
    7. Description of this illustration follows
    Description of the illustration.

Add the Conversation Marker to the HandleProblems State

As a business user, you want to view the agent handover separately from the HandleProblems intent. To separate the report by the SpeakToAgent transition, you're going to add the insightsEndConversation: true conversation marker to the properties node of the HandleProblems state:

handleProblems:
  component: "System.List"
    properties:
      insightsEndConversation: true   
      prompt: "I don't seem to be able to help you. Would you like to speak with someone?"
      ...
The marker should be six spaces from the left margin. Click Validate to ensure that the indentation is correct. 

View the Conversation Report

  1. Click The Skill Tester icon to open the Skill Tester.
  2. Click Reset.
  3. Enter I have a problem.
  4. Choose 1. Yes, I want to speak to someone.
  5. Close the Skill Tester.
  6. Open the Conversation report and then click Refresh. Notice that there are now two conversations: one for the HandleProblems intent, and a second called No Intent. The report labels this second conversation as No Intent because you did not enter any text that could be resolved to the LiveChat intent.
    7. Description of this illustration follows
    Description of the illustration.

section 6Optimize the OrderPizza Path

In this section, we're going to make the report easier to read by removing the supporting states for the ordering pizza execution path. While System.SetVariable states are vital to functioning of the skill, they may not be of interest to a business user who focuses on the states that support the ordering of the pizza.

Before you update the dialog flow to make the paths easier to read, take a look at full execution path for the OrderPizza intent:

  1. Click The Skill Tester icon to open the Skill Tester.
  2. Click Reset.
  3. Enter I want to order a small cheese basic pizza with onions.
  4. When the skill prompts you for a delivery address, choose Home. The skill then replies, "Thank you for your order, your Small CHEESE BASIC pizza with Onions will be delivered in 30 minutes at Home!"
  5. Close the Skill Tester
  6. Open the Intents report.
  7. Choose OrderPizza. Make sure that Completed is selected in the Outcome field.
  8. Note that the longest (and shortest, if this is your first invocation of the OrderPizza intent) is 6 states.
  9. In the Most Completed paths pane, review the path using the directional arrows (The arrow left icon and The arrow right icon) to see all of the states that were traversed through the pizza ordering process. Along with intent, orderPizza, and confirmation, the path includes three supporting states that a business user may not be interested in: setTextChannel, setAutoNumbering, and LoadPizzaCardInfo.
    10. Description of this illustration follows
    Description of the illustration.

Add Conversation Markers to the Supporting States of the OrderPizza Execution Flow

In this section, you're going to narrow the path down to just the intent, orderPizza, and confirmation states by adding the insightsInclude: false conversation marker to the properties nodes of the setTextChannel, setAutoNumbering, and LoadPizzaCardInfo states. When you're done, these states should look like this:

  setTextOnlyChannel:
    component: "System.SetVariable"    
    properties:
      insightsInclude: false
      variable: "textOnly"
      value: "${(system.channelType=='webhook')?then('true','false')}"
  setAutoNumbering:
    component: "System.SetVariable"    
    properties:
      insightsInclude: false
      variable: "autoNumberPostbackActions"
      value: "${textOnly}"
  # Loading additional info for each pizza type so we can use cards with an image and decription to present the various pizza types
  # The names of the pizza types must match the value list entries in the PizzaType entity.
  LoadPizzaCardInfo:
    component: "System.SetVariable"
    properties:
      insightsInclude: false
      variable: "pizzaCardInfo"

Each marker should be six spaces from the left margin. Click Validate to ensure that the indentation is correct.

View the Optimized Path

  1. Click The Skill Tester icon to open the Skill Tester.
  2. Click Reset, then replay the conversation by entering the following when prompted:
    • I would like to order a large cheese basic pizza with onions
    • Choose Home.
  3. Close the Skill Tester.
  4. Click Refresh in the Intents report.
  5. Make sure that OrderPizza is selected along with Completed in the Outcome field.
  6. Notice that the Shortest metric is 3 states. The Longest metric is 6 states.
  7. Notice that the path now includes the "essential" states: intent, orderPizza, and confirmation.
    8. Description of this illustration follows
    Description of the illustration.

section 7Optimize the LiveChat Path

In this step, we're going to optimize the path for the LiveChat intent by excluding the states that collect the user information that's passed to the live agent (if this skill were integrated with Oracle Service Cloud, that is). First, get acquainted with the execution path:

  1. Click The Skill Tester icon to open the Skill Tester.
  2. Click Reset.
  3. Enter I want to talk to a human.
    4. Description of this illustration follows
    Description of the illustration.
  4. Close the Skill Tester.
  5. Open the Conversations report and then click Refresh.
  6. Select the LiveChat conversation.
    7. Description of this illustration follows
    Description of the illustration.
  7. Scroll to the bottom of the page to view the execution path. It has five states, which include the supporting states: setupProfileFirstName, setupProfileLastName, and setupProfileEmail.
    8. Description of this illustration follows
    Description of the illustration.

Add Conversation Markers to the Supporting States of the LiveChat Execution Flow

Add insightsInclude: false to the properties nodes of the setupProfileFirstName, setupProfileLastName, and setupProfileEmail states. When you're done, these states should look something like this:

#####################################
# Service Cloud Live Chat Integration
#####################################
  setupProfileFirstName:
    component: "System.SetVariable"
    properties:
      insightsInclude: false 
      variable: "profile.firstName"
      value: "your first name" #Set this property
    transitions:
      next: "setupProfileLastName"
  setupProfileLastName:
    component: "System.SetVariable"
    properties:
      insightsInclude: false
      variable: "profile.lastName"
      value: "your last name" #Set this property
    transitions:
      next: "setupProfileEmail"
  setupProfileEmail:
    component: "System.SetVariable"
    properties:
      insightsInclude: false
      variable: "profile.email"
      value: "first.last@example.com" #Set this property
    transitions:
      next: "agentInitiation"

View the Optimized Path

  1. Click The Skill Tester icon to open the Skill Tester.
  2. Click Reset.
  3. Enter I want to talk to a human.
  4. After the skill responds, close the Skill Tester.
  5. Select the most recent LiveChat conversation, then scroll to the path rendered at the bottom of the page.
  6. Notice that the path now has just two states: intent, and state that's the focal point for a business user, agentInitiation.
    Description of this illustration follows
    Description of the illustration.

Congratulations! You've just learned how to make Insights reporting easier to read for business users.

more informationWant to Learn More?


C