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:
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:
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.
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.
However, when you trigger the textReceived transition by
entering text, the Conversation report names the resolved intent (OrderPizza,
OrderPasta).
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.
You can add the insightsInclude: false property to any state
that you don't wish to see in the Paths
report.
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.
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 🔗