Conversation Markers for Insights

C Conversation Markers for Insights

For skills with YAML-based dialog flows, you can make the Insights reports easier to read by adding the following conversation marker properties to the dialog flow:

insightsInclude: false – Excludes states from the dialog paths that are rendered in the Insights reports for Intents and Conversations. Adding this property to any state prevents it from being rendered or counted in the Insights reports, so you may want to apply it to states that play a supporting function, such as setting a variable value. For example, adding insightsInclude: false to each System.SetVariable property in a pizza skill reduces the path to only render the states for the skill-user interaction.
insightsEndConversation: true – Marks the end of the Insights reporting so that you can isolate the salient portion of the conversation. You can also use this marker to break down the reporting by transition.

You can add these properties to any state.

Model the Dialog Flow

By default, Insights tracks all of the states in a conversation, but you may not want to include all of them in the reports. To focus on certain transactions, or exclude the states from the reporting entirely, you can model the dialog flow using the insightsInclude and insightsEndConversation properties. These properties, which you can add to any component, provide a finer level of control over the Insights reporting.

Note

These properties are only supported on Oracle Digital Assistant instances provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure). They are not supported on instances provisioned on the Oracle Cloud Platform (as are all version 19.4.1 instances of Oracle Digital Assistant).

Mark the End of a Conversation

Instead of depending on the return transition to mark the end of a complete conversation, you can instead mark where you want to stop recording the conversation for insights reporting using the insightsEndConversation property. This property enables you to focus only on the aspects of the dialog flow that you're interested in. For example, you may only need to record a conversation to the point where a customer cancels an order, but no further (no subsequent confirmation messages or options that branch the conversation). By default, this property is set to false, meaning that Insights continues recording until a return transition, or until the insightsEndConversation property is set to true (insightsEndConversation: true).

  cancelOrder:
    component: "System.Output"
    properties:
      text: "Your order is canceled."
      insightsEndConversation: true 
    transitions:
      next: "intent"

Because this flag changes how the insights reporting views a completed conversation, conversation counts tallied after the introduction of this flag in the dialog flow may not be comparable to the conversation counts for previous versions of the skill.

Note

The insightsEndConversation marker is not used in the Visual Flow Designer because the modular flows already delineate the conversation. A conversation ends when the last state of a top-level flow has been reached.

Streamline the Data Collected by Insights

Use the insightsInclude property to exclude states that you consider extraneous from being recorded in the reports. To exclude a state from the Insights reporting, set this property to false:


...
  resolveSize:
    component: "System.SetVariable"
    properties:
      variable: "crust"
      value: "${iResult.value.entityMatches['PizzaSize'][0]}" 
      insightsInclude: false      
    transitions:
      ...
...

This property is specific to Insights reporting only. It does not prevent states from being rendered in the Tester.

Note

insightsInclude is not supported by the Visual Flow Designer.

Use Cases for Insights Markers

These typical use cases illustrate the best practices for making the reports easier to read by adding the conversation marker properties to the dialog flow.

Use Case 1: You Want to Separate Conversations by Intents or Transitions

Use the insightsEndConversation: true property to view the user interactions that occur within a single chat session as separate conversations. You can, for example, apply this property to a state that begins the execution path for a specific intent, yet branches the dialog flow.

The CrcPizzaBot skill's ShowMenu state, with its pizza, pasta, and textReceived transitions is such a state:

  ShowMenu:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      metadata:
        responseItems:
          - type: "text"
            text: "Hello ${profile.firstName}, this is our menu today:"
            footerText: "${(textOnly.value=='true')?then('Enter number to make your choice','')}"
            name: "hello"
            separateBubbles: true
            actions:
              - label: "Pizzas"
                type: "postback"
                keyword: "${numberKeywords.value[0].keywords}"
                payload:
                  action: "pizza"
                name: "Pizzas"
              - label: "Pastas"
                keyword: "${numberKeywords.value[1].keywords}"
                type: "postback"
                payload:
                  action: "pasta"
                name: "Pastas"
    transitions:
      actions:
        pizza: "OrderPizza"
        pasta: "OrderPasta"
        textReceived: "Intent"

By adding the insightsEndConversation: true property to the ShowMenu state, you can break down the reporting by these transitions:

  ShowMenu:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      insightsEndConversation: true
…

Because of the insightsEndConversation: true property, Insights considers any further interaction enabled by the pizza, pasta, or textReceived transitions as a separate conversation, meaning that two conversations, rather than one, are tallied in Overview page's Conversations metric and likewise, two separate entries are created in the Conversations report.

Note

Keep in mind that conversation counts will be inconsistent with those tallied prior to adding this property.

The first entry is for the ShowMenu intent execution path is where the conversation ends with the ShowMenu state.

Description of conversation_details_state_w_end_conversation.png follows

The second is the transition-specific entry that names an intent when the textReceived action has been triggered, or notes No Intent when there's no second intent in play. When you choose either Pizzas or Pastas from the list menu rendered for the showMenu state, the Conversation report contains a ShowMenu entry and a No Intent entry for the transition conversation because the user did not enter any text that needed to be resolved to an intent.

Description of no_intent_action_transition.png follows

However, when you trigger the textReceived transition by entering text, the Conversation report names the resolved intent (OrderPizza, OrderPasta).

Description of two_intents_textreceived_transition.png follows

Use Case 2: You Want to Exclude Supporting States from the Insights Pathing Reports

The states node of the CrcPizzaBot skill begins with a series of System.SetVariable states. Because these states are positioned at the start of the definition, they begin each path rendering when you haven't excluded them with the Filter States option. You may consider supporting states like these as clutter if your focus is instead on the transactional aspects of the path. You can simplify the path rendering manually using the Filter States menu, or by adding the insightsInclude: false property to the dialog flow definition.

Description of pathing_set_variable_included.png follows

You can add the insightsInclude: false property to any state that you don't wish to see in the Paths report.

  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}"
  setCardsRangeStart:
    component: "System.SetVariable"
    properties:
      insightsInclude: false
      variable: "cardsRangeStart"
      value: 0
    transitions:
      ...
...

For the CRCPizzaBotSkill, adding the insightsInclude: false property to each of the System.SetVariable states places the transactional states at the start of the path.

Description of pathing_set_variable_excluded.png follows

Note

Adding the insightsInclude: false property not only changes how the paths are rendered, but will impact the sum reported for the Average States metric.

Tutorial: Optimize Insights Reports with Conversation Markers

You can practice with conversation markers using the following tutorial: Optimize Insights Reports with Conversation Markers.