Oracle Cloud Infrastructure Documentation

Language

These are the components that are available in the Language category of YAML-based dialog flow editor.

System.Intent

This component detects the user intent and extracts all of the entities and then triggers a subsequent state.
Note

This component is not available for skills developed with the Visual Flow Designer. Instead, intents are resolved automatically when there is no active flow. See Intent Detection and Resolution.
Property Description Required?
variable Holds the value that the language processing framework resolves from the user input. For example, our sample skill bots define this property as variable=iResult (with iResult: "nlpResult" defined as one of the context variables). You don’t need to name the variable iResult. This name is a convention used in our sample code and sample skills. Whatever variable name you use for nlpResult, be sure to use it consistently across the dialog flow. Yes
optionsPrompt The title for the list of intents when you set a value for the Win Margin option. By default, this string value is Do you want to.

The default value for this property is stored in the skill's resource bundle. To change it, click Resource Bundles icon, select the Configuration tab, and update the Intent - optionsPrompt key. If you use the skill's resource bundle to change the default message, then you don't need to include the property in the component unless you want to override the default.

No
botName The name (not the display name) of the skill that resolves the intent. Use this property if you decide to resolve the user input using the model of a separate skill rather than the current skill. Using this approach might be beneficial if you want resolve the intent based on a model with a more narrowly defined domain than the domain required by your primary use case. No
botVersion Specifies the version of the skill. The default value is 1.0 (if you don't specify the version number). No
sourceVariable The language processing framework resolves the intent using the sourceVariable as the input.

Important: You can't use this property in combination with the translate property. If you need to translate the input represented by sourceVariable, you can use the System.TranslateInput to do so.

No
daIntercept For calls to System.Intent, determines whether the digital assistant can intercept and reroute the user input to other skills. These are the possible values:
  • always (the default)--Enables the digital assistant to intercept the input, even if the current flow has not ended. This enables the digital assistant to handle interruptions that suggest switching to another flow.
  • never--Prevents the digital assistant from intercepting the user input. For more on the use case for setting this value, see Enforce Calls to a Skill's System.Intent Component.
This property is ignored if the skill does not belong to a digital assistant. 		No
translate Overrides the value set for the autoTranslate context variable here. If autoTranslate is not set, or set to false, you can set this property to true to enable auto-translation for this component only. If the autotranslate context variable is set to true, you can set this property to false to exclude this component from auto-translation.

Important: You can't use this property in combination with the sourceVariable property. If you need to translate the input represented by sourceVariable, you can use the System.TranslateInput to do so.

No

Q&A Properties for the System.Intent Component

These are optional properties for Q&A routing.
Property Description Data Type Default Value
qnaEnable Enables the routing to the Q&A module. If you set this to true (routing enabled) you also need to define the Q&A transition action (none or exit). See Q&A Transitions. boolean false
qnaBotName The name (not the display name) of the skill with the Q&A module. If you don’t define this property, then the value defined for System.QnA component’s botName property is used instead. string N/A
qnaBotVersion The version of the skill with the Q&A module. By default, it's 1.0. This value is optional int N/A
qnaTimeout The time, in milliseconds, that the skill waits for the Q&A server to respond to the user input. long 5000
qnaUseResult Setting this option to true (the default), enables the skill to query the Q&A server with the user input. The skill then uses the results of this query (the matches) to set the routing. When you set this property to true, the skill will display the View Answers link only when there are matches. Setting it to false, displays the View Answers link at all times. boolean true
qnaSkipIfIntentFound When set to true, the skill bypasses Q&A when an there’s an intent match. The default value (false), enables the skill to query the QnA server with user utterance and also present QnA as an option. boolean false
optionsPrompt

Q&A is displayed if it’s enabled for the System.Intent component and we find a match.

Tip: For foreign (non-English) languages, reference a resource bundle. See Reference Resource Bundles in the Dialog Flow

 string Do you want to
optionsQnaLabel

A label for action in the options (optionsPrompt) that takes the user to the System.QnA component to display the matches.

Tip: For foreign (non-English) languages, reference a resource bundle. See Reference Resource Bundles in the Dialog Flow

 string Questions
qnaMatchFields Sets the Q&A fields used to match the user message. Valid values include:
  • all
  • categories
  • questions
  • answers
  • categories+questions
You can enter these values as a comma-separated list 		string all
qnaMinimumMatch

Sets the minimum and maximum percentage of tokens that any Q&A pair must contain in order to be considered a match.

To return the best matches, we tokenize the utterances that the Intent Engine resolves as questions. These tokens are formed from word stems and from various word combinations. As a result, a large set of tokens can be generated from an utterance. Because of this, it’s unlikely that any Q&A pair could contain all of the key words and variants. Therefore, we don’t recommend that you change this setting from its default, 50%,25%.

Having 50% of the generated tokens (the default maximum level) means that the Q&A pair can be considered a relevant match if it has all of the key words from the utterance. If this maximum level can’t be met, then a minimum level of 25% would suffice. If you change these settings—particularly by increasing the maximum to more than 50%—then the Q&A pair would not only need to contain all of the key words, but must also match additional tokens.

That said, if you want to reduce the chance of missing a relevant match—and can tolerate returning irrelevant matches in the process—then you can add an even lower threshold. For example: 50%,25%,10%.

If you want to minimize irrelevant matches, then you can increase the levels (say, 60%,50%). Keep in mind doing so might exclude Q&A pairs that have all of the keywords.

Important: If you don’t want to use the default levels, then you need to set the minimumMatch property and the Q&A Batch tester’s Match Thresholds option to the same values. See Batch Test the Q&A Module.

string 50%,25%
qnaUseSourceVariable When set to true, the Q&A matching is based on the value stored in the System.Qna’s sourceVariable property, not the user input. boolean false

System.MatchEntity

Note

This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Match Entity.

The System.MatchEntity calls the Intent Engine to extract entity information from the text held by the sourceVariable property. If a match exists for the variable's entity type, the variable is set with this entity value.

Property Description Required?
sourceVariable The variable that holds the input value. Yes
variable The name of the context variable. The value of this variable can be used in a subsequent System.SetVariable component to extract a specific entity using a FreeMarker expression. For example, to extract an EMAIL entity value: ${userInputEntities.value.entityMatches['EMAIL'][0]} Yes

This component also has two predefined transitions: match and nomatch.

Transition Description
match Directs the Dialog Engine to go a state when the entities match.
nomatch Defines the Dialog Engine to go to a state when the entities don’t match.
In the following snippet, System.MatchEntity component matches the user-provided value stored in the mailInput variable against the EMAIL entity type that’s been defined for the mailEntity variable. If the user input satisfies the entity type by being an e-mail address, then the System.MatchEntity component writes this value to the mailEntity variable that’s echoed back to the bot user ("You entered ${mailEntity.value.email}"). When the values don’t match, the Dialog Engine moves to the nomatch state.
Note

The System.MatchEntity component resolves a single value. 
context:
  variables:
    iResult: "nlpresult"
    mailInput: "string"
    mailEntity: "EMAIL"
states:
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        displayMailAdresses: "askMail"
        unresolvedIntent: "dunno"
  askMail:
    component: "System.Text"
    properties:
      prompt: "Please provide a valid email address"
      variable: "mailInput"
    transitions:
      next: "matchEntity"
  matchEntity:
    component: "System.MatchEntity"
    properties:
      sourceVariable: "mailInput"
      variable: "mailEntity"
    transitions:
      actions:
        match: "print"
        nomatch: "nomatch"
  print:
    component: "System.Output"
    properties:
      text: "You entered ${mailEntity.value.email}"
    transitions:
      return: "done"
  nomatch:
    component: "System.Output"
    properties:
      text: "All I wanted was a valid email address."
    transitions:
      return: "done"
  dunno:
    component: "System.Output"
    properties:
      text: "I don't know what you want"
    transitions:
      return: "done"

System.DetectLanguage

Note

This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Detect Language.
This component uses the translation service to detect the user’s language from the user input or from content that’s saved in a context variable that’s referenced by a source property: 
context:
  variables:
    autoTranslate: "boolean"
    translated: "string"
    someTranslatedText: "string"
states:
  setAutoTranslate:
    component: "System.SetVariable"
    properties:
      variable: "autoTranslate"
      value: true
    transitions:
      next: "detect"
   detect:
    component: "System.DetectLanguage"
    properties:
      source: "someTranslatedText"  
      useExistingProfileLanguageTag: true
    transitions:
      ...
The System.DetectLanguage component sets a variable named profile.languageTag with the locale string. You can set variables with the current language when you use this variable in a value expression (${profile.languageTag}).
Note

The profile.languageTag takes precedence over the profile.locale variable that’s set by the messenger client.

The useExistingProfileLanguageTag property is used when a skill is part of a digital assistant that has a translation service. This enables the skill to use the language that is detected by the digital assistant immediately. Otherwise, the skill might provide a message or prompt in English before the language is (re-)detected. If the skill is not in a translation-enabled digital assistant, the property is ignored.

The profile.locale and profile.languageTag Variables

The use of a particular resource bundle and the translations for both the UI labels the component messages themselves all depend on the user’s language that’s stored in the profile.locale and profile.languageTag variables.

The ways these variables get set depend on the language mode of the skill:

  • For skills that use native language support, the language is detected automatically and the these variables are populated with the appropriate value, unless the variables have already been assigned values.
  • For skills that use a translation service:
    • The value for the profile.locale variable is derived from the user’s messenger client.
      Note

      profile.locale supports values in ISO language-country or ISO language_country formats.
    • The value for the profile.languageTag variable is provided by the System.DetectLanguage component.
Note

The value set for the profile.locale variable can determine the locale-specific formats for the DATE, CURRENCY, and NUMBER entities even when a value has been set for the profile.languageTag variable.
You can set the value for both of these variables (and enable these variables to set values for one another) using the System.SetVariable. For example: 
  • setLocaleToGerman:
  component: "System.SetVariable"
  properties:
    variable: "profile.locale"
    value: "de"
  • setLanguageTagToGerman:
  component: "System.SetVariable"
  properties:
    variable: "profile.languageTag"
    value: "de"
  • setLanguageToVariableValue:
  component: "System.SetVariable"
  properties:
    variable: "profile.languageTag"
    value: "${language_preference_var.value}"
  • setLocaleToLanguageTag:
  component: "System.SetVariable"
  properties:
    variable: "profile.locale"
    value: "${profile.languageTag}"
  • setTagToLocale:
  component: "System.SetVariable"
  properties:
    variable: "profile.languageTag"
    value: "${profile.locale}"

Tip:

You can implement a choice list of languages by comparing the locale value stored in these variables, or in a custom user database table, against a list of supported languages. If the detected language isn’t on this list, you can prompt the user to choose one and then set the profile.languageTag with this value.

System.TranslateInput

Note

This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Translate Input.

This component sends specified text to the skill's translation service and then stores the English translation. It relies on the skill being configured with a translation service, which recognizes the language from the user's input and translates it into in English. This component doesn't work with skills that use the Natively Supported language mode.

Use this component when you need to process the raw input text before having it translated. For example, you might want to remove some personal data from the user input before sending it to the translation service.

Property Description Required?
source Specifies the text values to be translated into English. No
variable The variable that holds the English translation of the text. Yes

Because the System.TranslateInput component leverages the translation service, which already detects the user’s language, this component doesn’t need to follow states that detect or set the language as described in Add a Translation Service to Your Skill. As a result, you can store the English translation from direct user input, or from a source variable.

Direct Input Translation

The System.TranslateInput component stores the English translation of direct user input in its variable property. The following code snippet shows how user input like “Hallo, ich bin ein Mensch” in the translatedString variable is stored as “Hello, I am a human”.
context:
  variables:
     translatedString: “string”
     sourceString: “string”
...

states:
...

  translateInput:
    component: "System.TranslateInput"
      properties:
        variable: "translatedString"

The source Variable

In the following snippet, the sourceString variable holds the user input. (This input, for example, may have been gathered by a Common Response component.) After the System.TranslateInput completes its processing, the English translation is stored in the translatedString variable.
context:
  variables:
    autoTranslate: "boolean" 
    translatedString: "string"
    sourceString: "string"    

   ...

states:
   ...

  translateInputString:
    component: "System.TranslateInput"
    properties:
      source: "sourceString"
      variable: "translatedString"
    transitions: 
      ...
Note

The System.TranslateInput component can’t translate data objects or arrays that are stored in a context variable by a custom component. This content can only be translated when the variable is referenced by a component that uses autotranslation. For example, the System.TranslateInput component can’t translate a data object like {”product”: “scissors”, “color”: “silver”} as scissors and silver.

The sourceVariable Property

Because the System.Intent’s sourceVariable property holds the value processed by the component, you can use it with the System.TranslateInput component to insert translated text. The following snippet shows assigning the translated variable value so that it can be processed by the NLP engine. 

  translate:
    component: "System.TranslateInput"
    properties:
      variable: "translated"
    transitions: 
      next: "intent"
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
      sourceVariable: "translated"
...

System.TranslateOutput

Note

This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Translate Output.
The System.TranslateOutput component allows you to translate text to the user’s language. The component takes the value defined for the source property. It translates the text into the language detected by the System.DetectLanguage component or by the profile.locale variable and then stores it in the variable property.
Properties Description Required?
source The text to be translated, or a FreeMarker expression that references a variable whose value needs to be translated. Yes
variable Holds the translated text. Yes
In this example, the System.Output component, which would otherwise display autotranslated text, still outputs translated text, but here it outputs the translation of the text defined for the source property.
  unresolvedTranslate:
    component: "System.TranslateOutput"
    properties:
      source: "Sorry I don't understand"
      variable: "someTranslatedText"
    transitions:
      next: "unresolved"
  unresolved:
    component: "System.Output"
    properties:
      text: "${someTranslatedText}"
    transitions:
      return: "unresolved"

System.Qna

These are optional properties for the System.Qna component.
Name Description Required? Default Value
botName The name (not the display name) of the skill with the Q&A module. No N/A
botVersion The version of the skill that's identified by the botName property. You can define the botName property without also defining the botVersion property. However, you can't define botVersion without also defining botName: botVersion is ignored when you don't also define the botName property. As a consequence, its default version (1.0), only applies if you also define the botName property. To route to another version of the skill, you need to define the botName property and set the botVersion property with the target version. No 1.0
highlighter The method used to highlight the most relevant text in each answer. The valid values are:
  • system - the system tries to determine the most relevant text in the answer and highlights those words.
  • firstNChars - the first characters in the answer are highlighted. The number of characters is determined by the value of the highlightLength property plus the remaining characters in the final highlighted word.
No system
highlightLength The number of characters to be highlighted in each answer. No 100
sourceVariable The language processing framework resolves the Q&A matching using the value stored by the sourceVariable, not the user input. You activate this matching by setting qnaUseSourceVariable: true for the System.Intent component. For example:
metadata:
  platformVersion: "1.0"
main: true
name: "FinancialBotMainFlow"
context:
  variables:
    iResult: "nlpresult"
    iResult2: "nlpresult"
    transaction: "string"
    faqstring1: "string"
    faqstring2: "string"
states:

  ...  
  
  setVariable:
    component: "System.SetVariable"
    properties:
      variable: "faqstring1"
      value: "Tell me about family floater plan"

...

  intent2:
    component: "System.Intent"
    properties:
      variable: "iResult"
      sourceVariable: "faqstring1"
      qnaEnable: true
      qnaUseSourceVariable: true
    transitions:
      actions:
        Send Money: "sendMoney"
        Balances: "balances"
        unresolvedIntent: "unresolved"
        qna: "qna"

  sendMoney:
    component: "System.Output"
    properties:
      text: "send money"
    transitions:
      return: "sendMoney"

  balances:
    component: "System.Output"
    properties:
      text: "Balances"
    transitions:
      return: "balances"

  unresolved:
    component: "System.Output"
    properties:
      text: "Sorry I don't understand that question!"
    transitions:
      return: "unresolved"
  qna:
    component: "System.QnA"
    properties:
	    sourceVariable: "faqString1"
    transitions:
      actions:
        none: "unresolved"
      next: "intent2"
 No N/A
transitionOnTextReceived
Transitions from the state defined with the System.QnA component when the user enters free text.

  • true (the default)—Transitions from the System.Qna state when the skill receives any free text. Your skill can attempt to resolve this text when you configure a transition to a System.Intent state that’s configured with Q&A properties.

  • false—The Dialog Engine remains in the Q&A state, where the free text is treated as a Q&A query. The component also displays an exit option. By default, this button displays as Exit Questions, but you can change this using the exitLabel property.

    Because this adds the exit option, you need to configure the exit transition.

No true
keepTurn

The keepTurn property behaves differently depending on how the user transitions from the state defined with the System.QnA component. You can configure how keepTurn routes the user through the flow using a boolean (true, false) or with a map of key-value pairs.

No false (when configured as a boolean)
matchListLimit Limits the pagination for the answers No 5
categoryListLimit Limits the pagination of the categories No 5
resultLayout The layout for the matching answers. Valid values: horizontal and vertical. No horizontal
minimumMatch

Sets the minimum and maximum percentage of tokens that any Q&A pair must contain in order to be considered a match.

To return the best matches, we tokenize the utterances that the Intent Engine resolves as questions. These tokens are formed from word stems and from various word combinations. Depending on the length of the user message, the process can generate a large set of tokens. Because it's unlikely that any Q&A pair can match all of them, we recommend that you set the matching level at 50%, 25%.

In this setting, the Q&A pair can be considered a relevant if it matches 50% of the tokens. If this maximum level can’t be met, then a minimum level of 25% will suffice.

If you want to reduce the chance of missing a relevant match—and can tolerate returning irrelevant matches in the process—then you can add an even lower threshold as a fallback. For example: 50%,25%,10%.

If you want to minimize irrelevant matches, then you can increase the percentage (say, minimumMatch: "80%"), but doing so may result in unexpected matches for messages comprised of three-to-seven words. That said, you can tune the precision of the returned Q&A for both short and long user queries.

Important: If you don’t want to use the default levels when testing, then you need to set the QnaMinimumMatch property and the Q&A Batch tester’s Match Thresholds option to the same values that you've set for the minimumMatch property. See Batch Test the Q&A Module

 No 50%,25%
matchfields Sets the Q&A fields used to match the user message. Valid values include:
  • all
  • categories
  • questions
  • answers
  • categories+questions
You can enter these values as a comma-separated list. 		No all
enableCategoryDrilldown Set to true to display a drill down by category. No true
exitLabel The label text for exiting the Q&A module. No Exit Questions
viewAnswerLabel The label text for the view action for an answer detail. No View
moreAnswersLabel The label text for view action for more answers. No More Answers
answersLabel The label text for the view actions for answers in a specific category. No Answers
categoriesLabel The label text for the categories that match the utterance. No Categories
subCategoriesLabel The label text for the view action for the subcategories. No Sub-Categories
moreCategoriesLabel The label text for the view action for more categories. No More Categories

Increase the Precision of the Returned Q&A Using minimumMatch

While the default setting of 50%,25% returns accurate Q&A pairs, you may want your skill to return fewer, more precise results by increasing the percentage. For example, you may want your skill to only return a Q&A pair when it matches a high percentage of the tokens, or instead route the user to a live agent.

In such a scenario, increasing the percentage for the minimumMatch property to 80% can return more accurate Q&A matches, particularly for longer messages. The same may not be true for shorter messages, which are typically comprised of three to seven words, with about 50% of them being ignored words (stop words). For example, the user question What is account security? , for example, the system detects two tokens, account and security. When minimumMatch is set to 80%, only one of these tokens gets returned (80% of 2 is 1.6, which gets rounded down to 1), when ideally, both of them should. In this case, the skill might return Q&A pairs that generally describe accounts, which is too broad a response. The skill should have returned only the Q&A about account security, or returned nothing at all.

To configure the minimumMatch property to return accurate Q&A for short messages, enter the number of tokens that must be matched, a less-than operator (<) and the required matching level when the message contains a higher number of tokens. For example:
  qna:
    component: "System.QnA"
    properties:
      minimumMatch: "3<80%"
    transitions:
      actions:
        none: "unresolved"
      next: "intent"
In this snippet, if message contains 1 to 3 tokens, then the Q&A pair must match all of them for the skill to return it to the user. In terms of the scenario, this setting would only return a Q&A pair that matched account security. When the message has four or more tokens, then the Q&A pair only needs to match 80% of them.
You can tune the minimum match for longer messages that contain added details by graduating the number of required matching tokens (and simultaneously decreasing the percentage). For example, the following setting illustrates how to accommodate messages that can potentially contain more than nine tokens:
  qna:
    component: "System.QnA"
    properties:
      minimumMatch: "3<80% 8<70% 12<65%"  
    transitions:
      actions:
        none: "unresolved"
      next: "intent"
Per the minimumMatch setting in this snippet, the skill returns Q&A only when the following tokens are matched.
Number of Tokens in the Message The Number of Tokens that Must Match
1 1
2 2
3 3
4 (80% match) 3 (3.2, rounded down to 3)
5 (80% match) 4
6 (80% match) 4 (4.8, rounded down to 4
7 (80% match) 5 (5.6, rounded down to 5)
8 (80% match) 6 (6.4 rounded down to 6)
9 (70% match) 6 (6.3, rounded down to 5)
10 (70% match) 7
11 (70% match) 7 (7.7, rounded down to 7)
12 (70% match) 8 (8.4, rounded down to 8)
13 (65% match) 8 (8.45, rounded down to 8)

keepTurn key-value Maps and Transition Actions

You can define the keepTurn property as a map whose keys describe the transitions.
Key Description Default Value
next When set to false, the skill relinquishes control when the dialog transitions to the next state. The skill won’t process any user input until the Dialog Engine move to the next state. false
none When set to true, the skill retains control when a none transition action is triggered because there’s no question that can be returned for the user input. true
exit When set to true, the skill retains control when an exit transition action has been triggered. true
textReceived When set to true, the skill retains control of the conversation when transitionOnTextReceived is set to true which signals the Dialog Engine to transition from the state. true

Q&A Transitions

Name Description Required?
none No match found for the user input (which typically means that the flow routes to a state that informs the user that no such match was found). Yes
exit The user exits the Q&A module. By default, the keepTurn is set to true for this action. No