Oracle Cloud Infrastructure Documentation

A Built-In Components: Properties, Transitions, and Usage

Control Components

The control components route the flow based on whether the user input matches a predetermined value.

System.ConditionEquals

This component alters the navigation based on a variable value.

Use this component to branch the dialog flow when a value gets matched. This component executes value-based routing by comparing the values set for its source or variable properties against the value stored by the value property. The component triggers the equal and notequal actions accordingly based on a match (or lack thereof). In the following snippet, the customer gets routed to the orderPizza state when the input extracted for the orders context variable matches pizza, or to the execution path that begins with the orderPasta state when it doesn't.
  Check for Pizza:
    component: "System.ConditionEquals"
    properties:
      variable: "orders"
      value: "pizza"
    transitions:
      actions:
        equal:  "orderPizza"
        notequal: "orderPasta"
Properties Description Required?
variable The name of the variable whose current value determines the routing. The Dialog Engine ignores the variable property if you have also defined the source property. No
source The source property is an alternate to the variable property. No
value The value that's compared against either the source or variable properties. Yes
How Do I Use Apache FreeMarker Expressions with the System.ConditionEquals Component?
You you can narrow the matching criteria to specific values and formats by defining the value and source properties with Apache FreeMarker expressions. For example:
  • verifyCode:
        component: "System.ConditionEquals"
        properties:
          variable: "code"
          value: "${userEnteredCode.value}"
        transitions:
          actions:
            equal: "wrongCode"
            notequal: "${flow.value}"
    
  • conditionEquals:
        component:"System.ConditionEquals"
        properties:
          source: "${addressVariable.value.state} - ${addressVariable.value.country}"
          value: "CA - USA"
        transitions:
          actions:
            equal: goCalfifornia
            notequal: goSomewhereElse
  • main: true
    name: "Shoppingbot"
    context:
      variables:
        yesnoVar: "YES_NO"
        
    ...
    
     confirmBuy:
        component: "System.ConditionEquals"
        properties:
          source: "${yesnoVar.value.yesno}"
          value: "YES"
        transitions:
          actions:
            equal: "deviceDone"
            notequal: "cancelOrder"
      deviceDone:
        component: "System.Output"
        properties:
          text: "Your ${devices.value} is on its way."
        transitions:
          return: "done"
      cancelOrder:
        component: "System.Output"
        properties:
          text: "Thanks for your interest."
        transitions:
          return: "done"
  • context:
      variables:
        wordLength: "int"
        words: "string"
    states:
      askName:
        component: "System.Text"
        properties:
         prompt: "What is your name?"
         variable: "words"
      setVariable:
        component: "System.SetVariable"
        properties: 
          variable: "wordLength"
          value: "${words.value?length}"
      conditionEquals:
        component: "System.ConditionEquals"
        properties:
          source: "${(wordLength.value?number > 2)?then('valid', 'invalid')}"
          value: "valid"
        transitions:
          actions:
            equal: "checkFirstNameinDatabase"
            notequal: "inValidName"
      done:
        component: "System.Output"
        properties:
          text: "Done"
        transitions:
          return: "done"
      checkFirstNameinDatabase:
        component: "System.Output"
        properties:
          text: "Check the first name in the database."
        transitions:
          return: "done"
      inValidName:
        component: "System.Output"
        properties:
          text: "This name is not valid. It needs to be at least three letters."
        transitions:
          return: "done"

System.ConditionExists

Use this component to check for the existence of a specified variable. To route the dialog according to the value, define the transitions key using exists and notexist actions.

Properties Description Required?
variable The name of the variable Yes
main: true
name: "HelloKids"
context:
  variables:
    foo: "string"
    lastQuestion: "string"
    lastResponse: "string"
states:
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        Talk: "checkUserSetup"
        unresolvedIntent: "checkUserSetup"
  checkUserSetup:
    component: "System.ConditionExists"
    properties:
      variable: "user.lastQuestion"
    transitions:
      actions:
        exists: "hellokids"
        notexists: "setupUserContext"
  setupUserContext:
    component: "System.CopyVariable"
    properties:
      from: "lastQuestion,lastResponse"
      to: "user.lastQuestion,user.lastResponse"
    transitions: {}

...

System.Switch

Use this component to switch states based on a variable value.

Enables value-based routing similar to the System.ConditionEquals component. The System.ConditionEqual component selects an execution path by comparing a list of values against a variable or source property. When the values match, the component triggers an action transition that names the state that starts the execution path. You can add a NONE transition when the current value set for the variable doesn’t match any of the items defined for the values property. Configure the Dialog Flow for Unexpected Actions describes how the System.Switch component enables your skill bot to gracefully handle incorrect user input.
switchOnCategory:
    component: "System.Switch"
    properties:
      variable: "category"
      values:
      - "Vehicle"
      - "Property"
      - "Other"
    transitions:
      actions:
        NONE: ""ActionNoLongerAvailable"
        Vehicle: "getVehicleQuote"
        Property: "getPropertyQuote"
        Other: "getOtherQuote"
Property Description Required?
variable A variable whose current value is used as the basis for the switch transition. Define the values property as a list of comparison values. The Dialog Engine ignores the variable property when you have also defined the source property. No
source The source property is an alternate to the variable property. No
values The list of values used as comparisons against the source or variable properties. Yes
How Do I Use Apache FreeMarker Expressions with the System.Switch Component?
You you can narrow the matching criteria to specific values and formats by defining the value and source properties with Apache FreeMarker expressions. For example, you can define the expression using built-in FreeMarker operations, like date and string:
  switch2:
    component: "System.Switch"
    properties:
      source: "${startDate.value.date?string('dd-MM-yyyy')}"
      values:
      - "17-12-2017"
      - "18-12-2017"
    transitions:
      actions:
        "17-12-2017": goToday
        "18-12-2017": goTomorrow

Language

System.Intent

This component detects the user intent and extracts all of the entities and then triggers a subsequent state.
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 skill bots. 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. No
botName The name (not the display name) of the bot that resolves the intent. Use this property when you have a reusable bot that holds all of the intent and entity definitions. To support multiple languages, you can define this property with a variable expression that evaluates to a bot name based on the current language. 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. You can combine this with the System.TranslateInput component. No
daIntercept Enables digital assistant to intercept and reroute user input to the System.Intent component through the following values:
  • always (the default)--Enables the digital assistant to route 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.
This property is ignored (it's a no op) 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. 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
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

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 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: {}
  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

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: {}
   detect:
    component: "System.DetectLanguage"
    properties: {}
       source: "someTranslatedText"  
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 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 values for these two variables get set through different means. The System.DetectLanguagecomponent provides the value for the profile.languageTag variable. The value stored in the profile.locale variable is derived from the user’s messenger client.

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

This component stores the English translation of the user input. It relies on the translation service, which recognizes the user’s language from their input and translates it into in English. Use this component when you’ve activated a translation service, but you want to explicitly translate user input and not rely on the value of the autoTranslate context variable.
Property Description Required?
variable The variable that holds the English translation of the text. Yes.
source Specifies the text values to be translated into English. No

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 direct user input similar to another input component, the System.Text component. Unlike the System.Text component, the System.TranslateInput component’s variable property stores only English-translated text. The input stored by the System.Text’s variable property, on the other hand, holds the user input in its original language. 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 System.Text 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: {}

  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
      sourceVariable: "translated"
...

System.TranslateOutput

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: {}
  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%
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 only when it matches a high percentage of the tokens.

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

Security

System.OAuth2Client

Use this component to obtain an OAuth2 access token of grant type Client Credentials. That is, you use it to get an access token that's based on the client's credentials, and not the user's name and password. You can use this component to get a token that enables access to client resources that are protected by Oracle Identity Cloud Service or Oracle Access Manager (OAM).

If you need to access resources on behalf of a user, see System.OAuth2AccountLink and System.OAuthAccountLink.

Before you can use this component in a skill, you must do the following tasks:

  1. If it isn't already registered, register the client with the identity provider as described in Identity Provider Registration.
  2. Add a client-credentials authentication service for the identity provider, as described in Authentication Services.
Property Description Required?
authenticationService The name of the client-credentials service that you created in the Authentication Services UI for the OAuth2 identity provider. Yes
accessTokenVariableName Specifies the variable to store the access token in. You can declare it in the context node as a variable, a string, or another supported variable type. It also can be a user-scoped variable. For example: user.accessToken. Yes

This component doesn't have any actions. To handle system problems that might occur, add a next transition that goes to a state that can handle such errors.

Here's an example of a state that uses this component:

  getAccessToken:
    component: "System.OAuth2Client"
    properties:
      authenticationService: "myAuthenticationService"
      accessTokenVariableName: "myAuthServiceToken"
    transitions:
      next: "next"
      error: "error" # handle auth service issues

System.OAuth2AccountLink

Use this component to obtain an OAuth2 user access token (grant type Authorization Code) for resources that are secured by Oracle Identity Cloud Service or Oracle Access Manager (OAM). This component completes all the steps for the 3-legged OAuth2 flow and returns the OAuth2 access token.

If you need to obtain an access token of grant type Client Credentials to access client resources, see System.OAuth2Client.

Before you can use this component in a skill, you must do the following tasks:

  1. If it hasn't been registered already, then register the client with the identity provider as described in Identity Provider Registration.
  2. Add an authentication service for the identity provider, as described in Authentication Services.

Some identity providers issue refresh tokens. When you use this component, Digital Assistant stores the refresh token for the retention period that's specified for the authentication service. When an access token expires, the Digital Assistant backend can use the refresh token, if available, to get a new access token without the user having to sign in again.

Property Description Required?
accessTokenVariableName Specifies the variable to store the access token in. If your context variable is named accessToken, then you can omit this property. No
authenticatedUserVariableName Specifies the variable in which to store the authenticated user name (the name that’s known by the identity provider). If your context variable is named authenticatedUser, then you can omit this property. No
authenticationService The name of the authorization-code service that you created in the Authentication Services UI for the OAuth2 identity provider. Yes
autoNumberPostbackActions When set to true, this option prefixes a number to the cancel option, which is a server-side postback action. It doesn't prefix a number to the option to get an access token because that is a URL action, which is a client-side action that can't be prefixed with a sequence number.

Even when you haven’t set this option to true, auto-numbering can be enforced on postback actions when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true. Channel-specific auto-numbering can be applied to any skill bot that's registered to a digital assistant:

${(system.message.channelConversation.channelType=='twilio')?then('true','false')}

See Auto-Numbering for Text-Only Channels and

Auto-Numbering for Digital Assistants

No
cancelLabel Use to override the label for the button that the users can click to leave state without invoking the authentication dialog. The default label is Cancel. No
footerText Enhances the login dialog by adding text beneath the login and cancel options. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. No
linkLabel Use to override the label for the button that the users can click to invoke the authentication dialog. The default label is Get an access token. No
prompt The string to use to prompt the user instead of the default Please sign in. No
showCancelOption (Optional) Enables you to specify whether or not to display the Cancel button. By default, this option is set to true, meaning that the Cancel button is displayed. In some cases, such as for SMS channels, you might not want to display this button. You can configure such behavior with an expression like:
${(system.message.channelConversation.channelType=='twilio')?then('false','true')}
No
translate Use this optional boolean property to override the boolean value of the autoTranslate context variable. Note that autoTranslate is false (exclude from autotranslation) unless that context variable has been explicitly set to true. No

This component can return the following actions:

Action Description
fail The user clicked the cancel button.
pass The access token was retrieved successfully.
textReceived The user entered text instead of clicking the cancel button or authenticating successfully.

Tip:

Before calling a state that uses component, your dialog flow should check the ${system.security.configuredAuthenticationServices} variable to verify that the authentication service is configured in the instance. For example:

  verifyAuthService:
    component: "System.ConditionEquals"
    properties:
       source: <#if "${system.security.configuredAuthenticationServices}"?contains("MyAuthenticationService")>true<#else>false</#if>
       value: "true"
    transitions:
       actions:
         equal: getAccessToken
         notequal: noAuthentication

In the next example, when the dialog engine encounters the component, the skill bot prompts the user with two links: Get an Access Token and Cancel.


Description of oauth2accountlinksignin1.png follows
Description of the illustration oauth2accountlinksignin1.png

If the user clicks the link to get an access token, it displays the identity provider’s login page or authentication dialog as specified by the authentication service named MyAuthenticationService. After successful login, it obtains the access, sets the myAccessToken and myAuthenticatedUser context variables, and then flows to the state that's named by the pass action (or to the next state if there isn't a pass action). If the user cancels, the postback action is set to fail. If the user enters text, it returns the textReceived action.


Description of oauth2accountlinksignin2.png follows
Description of the illustration oauth2accountlinksignin2.png

context:
  variables: 
    myAccessToken: string
    myAuthenticatedUser: string
states:
  verifyAuthService:
    component: System.ConditionEquals
    properties: 
      source: <#if "${system.security.configuredAuthenticationServices}"?contains("MyAuthenticationService")>true<#else>false</#if>
      value: "true"
    transitions:
      actions:
         equal: getAccessToken
         notequal: noAuthService
  getAccessToken:
    component: System.OAuth2AccountLink
    properties:
      authenticationService: MyAuthenticationService
      accessTokenVariableName: myAccessToken
      authenticatedUserVariableName: myAuthenticatedUser
    transitions:
      actions:
        pass: getBankUserProfile
        textReceived: handleAuthTextResponse
        fail: authCancelled
...
Handle Multiple Authentication Services

If the skill bot needs access tokens from multiple authentication services, you can specify unique access-token and authenticated-user variable names for each use of this component as shown in this example:


context:
  variables:
    accessToken1: string 
    authenticatedUser1: string
    accessToken2: string 
    authenticatedUser2: string
    code: string
states:
# First Authentication Service
  verifyAuthService1:
    component: System.ConditionEquals
    properties:
       source: <#if "${system.security.configuredAuthenticationServices}"?contains("authService1")>true<#else>false</#if>
       value: "true"
    transitions:
       actions:
         equal: getAccessToken1
         notequal: noAuthService
  getAccessToken1:
    component: System.OAuth2AccountLink
    properties:
      variable: code
      authenticationService: authService1
      accessTokenVariableName: accessToken1
      authenticatedUserVariableName: authenticatedUser1
    transitions:
      actions:
        pass: verifyAuthService2
        textReceived: handleAuthTextResponse
        fail: authCancelled
# Second Authentication Service
  verifyAuthService2:
    component: System.ConditionEquals
    properties:
       source: <#if "${system.security.configuredAuthenticationServices}"?contains("authService2")>true<#else>false</#if>
       value: "true"
    transitions:
       actions:
         equal: getAccessToken2
         notequal: noAuthService
  getAccessToken2:
    component: System.OAuth2AccountLink
    properties:
      variable: code
      authenticationService: authService2
      accessTokenVariableName: accessToken2
      authenticatedUserVariableName: authenticatedUser2
    transitions:
      actions:
        pass:  getBankUserProfile
        textReceived: handleAuthTextResponse
        fail: authCancelled
...
Handle an Expired Access Token

If the access token has expired, the custom component should return a failure action such as unauthorized. Upon a failure action, the dialog flow should transition to the state that uses the OAuth2AccountLink component to get a new access token.

Here’s an example flow for handling an expired access token. The get.file custom component returns unauthorized whenever an expired access token is passed in. This flow handles the unauthorized action by transitioning to the accessTokenError flow to get a new token. The OAuth2AccountLink component is invoked again, and the new access token is passed to the custom component.

context:
  variables:
    iResult: nlpresult
    accessToken: string
    returnTo: string
    path: string
    authenticatedUser: string
states:
  startFlow:
    component: System.SetVariable
    properties:
      variable: returnTo
      value: intentFlow
    transitions:
      next: getAccessToken

  #
  # Flow for getting the user's intent
  #
  intentFlow:
    component: System.ResetVariables
    properties:
     variableList: path
  greeting:
    component: System.Output
    properties:
      text: "What do you want to do (examples: get file, put file)?"
  intent:
    component: System.Intent
    properties:
      variable: iResult
    transitions:
      actions:
        putFileFlow: putFileFlow
        getFileFlow: getFileFlow
        goodbye: goodbye
        unresolvedIntent: unresolved
  #
  # Flow for getting an access token
  #
  getAccessToken:
    component: System.OAuth2AccountLink
    properties:
      prompt: "Authorization"
      authenticationService: myService
      authenticatedUserVariableName: authenticatedUser
      accessTokenVariableName: accessToken
      translate: false
    transitions:
      actions:
        pass: ${returnTo.value}
        textReceived: handleAuthTextResponse
        fail: authCancelled    
  #
  # Flow for authentication error (expired access token)
  #
  accessTokenError:
    component: System.Output
    properties:
      text: "Let's get another access token."
      keepTurn: true
  getNewToken:
    component: System.ResetVariables
    properties:
     variableList: accessToken
    transitions:
      next: getAccessToken

  #
  # Flow for getting a file
  #
  getFileFlow:
    component: System.SetVariable
    properties:
      variable: returnTo
      value: getFile
  getFilePath:
    component: System.Text
    properties:
     prompt: "What's the path of the file that you want to get?"
     variable: path
  getFile:
    component: get.file
    properties:
      accessToken: "${accessToken.value}"
      path: "${path.value}"
      keepTurn: true
    transitions:
      actions:
        success: intentFlow
        failure: intentFlow
        unauthorized: accessTokenError
...

System.OAuth2ResetTokens

Use this component to revoke all the logged-in user's refresh and user access tokens from the identity provider that the authentication service represents. It also removes the refresh tokens from the database. To use this component, you must provide the identity provider's revoke refresh token URL in the Authentication Service UI.

The skill must include a state that uses the OAuth2AccountLink component for the same authentication service, and it must be invoked before the state that uses the System.OAuth2ResetTokens component.

Property Description Required?
authenticationService The name of the service that you created in the Authentication Service UI for the OAuth2 identity provider. This service must have a valid revoke refresh token URL. Yes

System.OAuthAccountLink

Use this component to obtain the authorization code for services that are secured by the authorization code grant flow, such as LinkedIn, Twitter, Google, or Microsoft. The skill’s custom components can exchange the authorization code for an access token, which they then use to invoke the end service.

The component first directs the user to the identity provider’s login page. After a successful login, the component returns the authorization code in a variable, which you use to pass the authorization code to the custom component. The custom component API must exchange the authorization code, client ID, and client secret for an OAuth2 user access token.

Before you can use this component in a skill, you must register the client with the identity provider as described in Identity Provider Registration.

Property Description Required?
authorizeURL The login URL. The authorizeURL Property describes how to configure this URL. Yes
autoNumberPostbackActions When set to true, this option prefixes a number to the cancel option. Even when you haven’t set this option to true, auto-numbering can be enforced on list items when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true. Channel-specific auto-numbering can be applied to any skill bot that's registered to a digital assistant:
${(system.message.channelConversation.channelType=='twilio')?then('true','false')}
No
cancelLabel Use to override the label for the button that the users can click to leave state without invoking the authentication dialog. The default label is Cancel. No
footerText Enhances the login dialog by adding text beneath the login and cancel options. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. No
linkLabel Use to override the label for the button that the users can click to invoke the authentication dialog. The default label is Log In. No
prompt The string to use to prompt the user to sign in. Yes
showCancelOption (Optional) Enables you to specify whether or not to display the Cancel button. By default, this option is set to true, meaning that the Cancel button is displayed. In some cases, such as for SMS channels, you might not want to display this button. You can configure such behavior with an expression like:
${(system.message.channelConversation.channelType=='twilio')?then('false','true')}
Yes
translate Use this optional boolean property to override the boolean value of the autoTranslate context variable. Note that autoTranslate is false (exclude from autotranslation) unless that context variable has been explicitly set to true. No
variable Specifies the variable to store the authorization code in. You can declare it in the context node as a variable, a string, or another supported variable type. It can also be a user variable. Yes

This component can return the following actions:

Action Description
fail The user clicked the cancel button.
pass The authorization code was retrieved successfully.
textReceived The user entered text instead of clicking the cancel button or authenticating successfully.

This example shows the required properties that you need to define for the System.OAuthAccountLink component: prompt, which specifies the login message, variable, which tells the component where to store the authorization code, and authorizeURL which defines both the provider’s OAuth URL and the redirect URL that receives the authorization code.

login:
  component: "System.OAuthAccountLink"
  properties:
    prompt: "Please login now."
    linkLabel: "login"
    cancelLabel: "cancel"
    authorizeURL: "https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=75k0vq4&scope=r_basicprofile&redirect_uri=https%3A%2F%2FmyBotsinstance%2Fconnectors%2Fv1%2Fcallback"
    variable: "authCode"
  transitions:
      next: getBankUserProfile
      actions:
        textReceived: handleAuthTextResponse
        fail: authCancelled

When the dialog engine encounters this component, the skill bot prompts the user with two links — Login and Cancel.

There are several ways to transition from this component:

  • The user clicks the cancel button and the component transitions to the state that's named by the fail action.

  • The user doesn't click any buttons but enters text instead. The component transitions to the state that's named by the textReceived action.

  • The user clicks the login link and the channel renders the identity provider’s login page or its authentication dialog as a webview, as shown in the example below. After successful authorization, the component transitions to the state that's named by the pass action (or to the next state if there isn't a pass action), which would typically call a custom component that exchanges the authorization code for an access token.

If the test window doesn’t render the webview, cut and paste the link text into your browser.

The authorizeURL Property
To configure this property, you begin with the identity provider’s URL, such as https://www.linkedin.com/oauth/v2/authorization in the example. Next, append the following OAuth parameters to this URL:
  1. response_type: Set to code because the skill bot expects an authorization code.

  2. client_id: The API key value that you got when you registered your app with the identity provider.

  3. scope: A list of permissions to access resources on the user’s behalf. These are the permissions that you set when you register your app with the provider. They can vary by provider: for LinkedIn, these include r_basicprofile (shown in the example) and r_emailadress; for Microsoft, they’re defined using openid email and openid profile.

  4. redirect_uri: This is the redirect URI that you used to register your app with the identity provider, and tells the provider where to redirect users. This parameter, which is the Digital Assistant service host name appended with connectors/v1/callback, is the endpoint that receives the authorization code and then associates it with the active channel. The redirect_uri property is based on the Webhook URL that’s generated when you create a channel. See What Are Channels?
    Note

    Be sure that the value you enter for the redirect_uri matches the redirect URI that you provided when you registered your app exactly. In both instances, the URI must be appended with connectors/v1/callback.

User Interface Components

Use these components to display text:

System.Text

The System.Text component enables your bot to set a context or user variable by asking the user to enter some text.

When the Dialog Engine enters a System.Text state for the first time, it prompts the user to enter some text. When the user enters a value, the Dialog Engine returns to this state. The component processes the user response and if it can convert the user input to the variable type, it stores the value in the variable. The Dialog Engine moves on to another state when this variable has a value.
Note

The Dialog Engine skips over the System.Text state of the variable already has a value.
Property Description Required?
prompt A text string that describes the input required from the user. You can dynamically add values to it using a value expression. For example: Hello ${profile.firstName}, how many pizzas do you want? Yes
variable The name of the variable, which can be either a user variable or one of the variables declared in the context node. Yes
nlpResultVariable Sets the variable property with an entity value (when that entity value hasn’t already been set for the referenced variable). You can enable nlpResultVariable to return value when you define it using a variable that holds the NLP results (such as iresult: "nlpresult" that’s used in our sample bots). By doing this, the nlpResultVariable property can still populate the value when it’s null if it finds a resolved entity that matches the one referenced by the variable. The dialog transitions to the next state when the nlpResultVariable sets the value. You can use this property in place of the System.SetVariable component. No
maxPrompts The number of times that component prompts the user for valid input. See Limiting the Number of User Prompts. No
translate Use this property to override the boolean value that you’ve set for the autotranslate context variable. If you haven’t set this variable, or if you set it to false, then you can set this property to true to enable autotranslation for this component only. If you set the autotranslation variable is set to true, you can set this property to false to exclude this component from autotranslation. See Translation Services. No

See Transitions for the predefined action types that you can use with this component.

How Do I Use the System.Text Component?

In this example, the type variable holds the values expected by the PizzaType entity, like cheese, Veggie Lover, and Hawaiian. When this information is missing from the user input, the bot can still get it because its dialog flow transitions to the type state, whose System.Text component prompts them to explicitly state what they want. Keep in mind that even at this point, the user input still needs to resolve to the PizzaType entity to transition to the next state.

main: true
name: "PizzaBot"
parameters:
  age: 18
context:
  variables:
    size: "PizzaSize"
    type: "PizzaType"
    crust: "PizzaCrust"
    iResult: "nlpresult"

...

  type:
    component: "System.Text"
    properties:
      prompt: "What Type of Pizza do you want?"
      variable: "type"
    transitions: {}

System.List

Your bot can use the System.List component to set a user or context variable or set a transition action. The mode depends on whether a value can be set for the component’s variable property (or if you configure a variable property in the first place).

When the Dialog Engine enters a System.List state for the first time, your bot displays a message containing a list of options. When the user clicks one of these options, the Dialog Engine returns to the System.List state to process the user response. If the component can convert the selected option to a user variable or one of the variables that you’ve defined in the context node, then the System.List’s variable property it sets the variable property with this value. When this property can’t be set (or hasn’t been defined), the Dialog Engine triggers a transition action instead.
Property Description Required?
options You can specify the options using comma-separated text strings, Apache FreeMarker expressions, and as a list of maps. Yes
prompt The text string that prompts the user. Yes
variable The name of the variable whose value is populated by the user input. The Dialog Engine skips this state if the variable value has already been set and doesn’t output the list options for the user.  No
nlpResultVariable Sets the variable property with an entity value (when that entity value hasn’t already been set for the referenced variable). You can enable nlpResultVariable to return value when you define it using a variable that holds the NLP results (such as iResult: "nlpresult" that’s used in our sample bots). By doing this, the nlpResultVariable property can still populate the value when it’s null if it finds a resolved entity that matches the one referenced by the variable. The dialog transitions to the next state when the nlpResultVariable sets the value. You can use this property in place of the System.SetVariable component. No—Use this property when the variable property names an entity-type variable.
maxPrompts The number of times that component prompts the user for valid input. See Limiting the Number of User Prompts. No
translate Use this property to override the boolean value that you’ve set for the autotranslate context variable. If you haven’t set this variable, or if you set it to false, then you can set this property to true to enable autotranslation for this component only. If you set the autotranslation variable is set to true, you can set this property to false to exclude this component from autotranslation. See Translation Services. No
autoNumberPostbackActions When set to true, this option prefixes numbers to options. Even when you haven’t set this option to true, auto-numbering can be enforced on list items when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true. Channel-specific auto-numbering can be applied to any skill that's registered to a digital assistant:${(system.message.channelConversation.channelType=='twilio')?then('true','false')} No
footerText Enhances the output on text-only channels. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. No
See Transitions for the predefined action types that you can use with this component.
Value Lists

You can use the System.List component to return a value that satisfies a context variable that’s defined as a primitive (like greeting: "string" in the dialog flow template) or as an entity, as shown in the following snippet. In this dialog flow, the options: "Thick,Thin,Stuffed,Pan" definition returns a value that matches crust variable. The options property defined for size is a value expression (${size.type.enumValues}) that returns the Large, Medium, Small, and Personal list values as options. See Apache FreeMarker Template Language Syntax.

This example also shows how the nlpResultVariable property’s iResult definition allows the component to set the entity values for the variable properties for the crust and size states when these values haven’t been previously set. Like the Text component, the System.List component doesn’t require any transitions ({}).
main: true
name: "PizzaBot"

...

context:
  variables:
    size: "PizzaSize"
    crust: "PizzaCrust"
    iResult: "nlpresult"

...

states:

...

crust:
  component: "System.List"
  properties:
    options: "Thick,Thin,Stuffed,Pan"
      prompt: "What crust do you want for your pizza?"
      variable: "crust"
main: true
name: "PizzaBot"

...

context:
  variables:
    size: "PizzaSize"
    crust: "PizzaCrust"
    iResult: "nlpresult"
...

states:

...

crust:
   component: "System.List"
   properties:
     options: "Thick,Thin,Stuffed,Pan"
     prompt: "What crust do you want for your pizza?"
     variable: "crust"
     nlpResultVariable: "iresult"
   transitions: {}
size:
   component: "System.List"
   properties:
     options: "${size.type.enumValues}"
       prompt: "What size Pizza do you want?"
       variable: "size"
       nlpResultVariable: "iresult"
    transitions: {}

The list component in a live chat.
Note

Users aren’t limited to the options displayed in the list. They can resolve the entity by entering a word that the entity recognizes, like a synonym. Instead of choosing from among the pizza size options in the list, for example, users can instead enter big, a synonym defined for the PizzaSize entity’s Large option. See Custom Entities.
The list component with user input.
The options Property
You can set the options property using any of the following:
  • A list of maps—While you can set the options property as a text string or value expression, you can also configure the options property as list of maps. Each one has a label property, a value property, and an optionalkeyword property. You can localize your list options when you follow this approach because, as noted by the following example, you can reference a resource bundle. See Resource Bundles to find out more about using the dot notation. When users enter a value that matches one the values specified in the keyword property, the bot reacts in the same way that it would if the user tapped the list option itself.
    askPizzaSize:
      component: "System.List" 
      properties:
        prompt: What size do you want?"
        options:
        - value: "small"
          label: "${rb.pizza_size_small}"
          keyword: "1"
        - value: "medium"
          label: "${rb.pizza_size_medium}"
          keyword: "2" 
        - value: "large"
          label: "${rb.pizza_size_large}"
          keyword: "3" 
       variable: "pizzaSize"
  • A text string of comma-separated options, like “small, medium, large” in the following snippet. You can’t add label and value properties when you define options as a string.
    askPizzaSize:
      component: "System.List"
      properties: 
        prompt: "What size do you want?"
        options: "small, medium, large"
        variable: "pizzaSize"
    
  • An Apache FreeMarker value expression that loops over either a list of strings, or a list of maps, where each map must contain both the label and value properties and optionally, a keyword property.
    askPizzaSize:
      component: "System.List" 
      properties:
        prompt: "What size do you want?"
        options: "${pizzaSize.value.enumValues}"
        variable: "pizzaSize"
Refer to the Apache FreeMarker Manual to find out more about the syntax.
Action Lists
You don’t need to define the variable property for a System.List option when you’re configuring a list of actions. In this case, the component sets a transition action based on the option selected by the user. For example:
showMenu:
  component: "System.List" 
  properties:
    prompt: "Hello, this is our menu today"  
    options:

    - value: "pasta"
      label: "Pasta"
    - value: "pizza"
      label: "Pizza"

  transitions:
    actions:
      pasta: "orderPasta"
      pizza: "orderPizza"

Tip:

Not only can you use this approach to configure conditional navigation, you can use an action list in place of a System.Switch component.

System.Output

Use the System.Output component to output a message that doesn't require a user response, or doesn't require your bot to process the user's response. If you need to process the user’s message, use either the System.Text or the Systen.CommonResponse component.

Your System.Output component definition requires the text property. As illustrated in the following example of a confirmation message, you can add value expressions to this string.
done:
    component: "System.Output"
    properties:
      text: "Your ${size.value}, ${type.value} pizza with ${crust.value} crust is on its way. Thank you for your order."
By default, the Dialog Engine waits for user input after it outputs a statement from your bot. If you override this behavior, add the optional property called keepTurn to the System.Output component definition and set it to true to direct the Dialog Engine to the next state as defined by the transitions property. When no transition as been defined, the Dialog Engine moves to the next state in the sequence.
  wait:
    component: "System.Output"
    properties:
      text: "Please wait, we're reviewing your order"
      keepTurn: true
    transitions:
      next: "ready"
 waitmore:
    component: "System.Output"
    properties:
      text: "Almost done..."
      keepTurn: true
    transitions:
      next: "done"
  done:
    component: "System.Output"
    properties:
      text: "Your ${size.value}, ${type.value} pizza with ${crust.value} crust is on its way. Thank you for your order."
    transitions:
      return: "done"

Use the keepTurn option when you want output multiple statements in quick succession and without user interruptions.

Defining Value Expressions for the System.Output Component
You can define one or more value expressions for the text property, as in the following snippet that uses different expressions for outputting the text for an order confirmation (pizza size and type).
confirmation:
    component: "System.Output"
    properties:
      text: "Your ${size.value} ${type.value} pizza is on its way."
    transitions:
      return: "done" 
Your bot outputs raw text when these expressions return a null value for the variable. If you’re defining the text property with multiple expressions, each one must return a value. Otherwise, your bot users will see output text like:
Your ${size.value} ${type.value} is on its way.
It’s all or nothing. To make sure that your bot always outputs text that your users can understand, substitute a default value for a null value using the Apache Freemarker default value operator: ${size.value!\”piping\”} ${type.value!\”hot\”}. The double quotes indicate that the default value is a not a variable reference, but is instead the constant value that the operator expects. For example:
text: "Your ${size.value!\"piping\"} ${type.value!\"hot\"} pizza is on its way."
Note

Always escape the quotation marks (\"...\") that enclose the default value when you use the Freemarker operator. Your dialog flow’s OBotML syntax won’t be valid unless you use this escape sequence whenever you define a default value operation, or set off output text with double quotes. For example, the following System.Output component definition lets bot users see You said, “Cancel this order.”
confirmCancel:
    component: "System.Output"
    properties:
      text: "You said, \"Cancel this order.\""
    transitions:
      return: "cancelOrder"
Translating Output Text
You can suppress or enable the System.Output component’s autotranslated text on a per-component basis using the translate property. By setting it to false, as in the following snippet, the components outputs the text as is, with no translation. By setting this property to true , you can enable autotranslation when the autoTranslate variable is either set to false or not defined. See Translation Services.
Note

Typically, you would not set the autoTranslate variable to true if you’re translating text with resource bundles. We do not recommend this approach.
setAutoTranslate:
    component: "System.SetVariable"
    properties:
      variable: "autoTranslate"
      value: "true"
    transitions: {}
...
pizzaType:
   component: "System.Output"
   properties:
     text: "What type of pizza do you want?"
     translate: false
   transitions: {}

System.CommonResponse

The System.CommonResponse component enables you to build a specialized user interface that can include text, action buttons, images, and cards without having to write custom code. Instead, you define the component’s properties and metadata.

You can see an example of using the System.CommonResponse component in the CrcPizzaBot, one of the sample bots. In this spin on the PizzaBot, you can display an image-rich menu with quick action “Order Now” buttons. Within the context of the System.CommonResponse component, the different types of messages are known as “response types” and the CrcPizzaBot shows you how, among other things, they allow the bot users to respond to prompts using action buttons and view the pizza menu as a cascade of card items.

From the Add Components menu, you can select different System.CommonResponse templates for cards, text, attachment responses, and for composite bag entities (demonstrated by the CbPizzaBot). These templates include both properties that are common to all of these response type properties that are specific to the individual response types. While the Add Components menu adds separate states for each response type, you can combine one or more response types into a single state. The CrcPizzaBot shows you examples of both in its ShowMenu (text response) and OrderPizza (text and card responses) states.

Note

Some channels have limitations in how they can render components, and those limitations are not reflected in Digital Assistant's tester. You should test each skill in your target channels early in the development cycle to make sure that your components render as desired.
The Component Properties
As shown in the following OBotML snippet from the CrcPizzaBot, configuring the System.CommonResponse component includes setting properties that direct the Dialog Engine along with metadata properties that describe not only how the component delivers messages (as text prompts, cards, or attachments), but also sets the content and behavior for the messages themselves.
  AskPizzaSize:
    component: "System.CommonResponse"
    properties:
      variable: "pizzaSize"
      nlpResultVariable: "iresult"
      maxPrompts: 2
      metadata:
        responseItems:
        - type: "text"
          text: "<#if system.invalidUserInput == 'true'>Invalid size, please try again.\
            \ </#if>What size do you want?"
          name: "What size"
          separateBubbles: true
          actions:
          - label: "${enumValue}"
            type: "postback"
            payload:
              action: ""
              variables:
                pizzaSize: "${enumValue}"
            name: "size"
            iteratorVariable: "pizzaSize.type.enumValues"
      processUserMessage: true
    transitions:
      actions:
        cancel: "Intent"
      next: "AskLocation" 

Tip:

The text property in this snippet is defined using Apache FreeMarker Template Language (FTL). To find out how to add FTL expressions and use FreeMarker built-in operations to transform variable values, see Apache FreeMarker Template Language Syntax.
Name Description Required?
metadata The chat response created by this component is driven by the contents of the metadata property. See The Metadata Property. Yes
processUserMessage Set this property to true to direct the Dialog Engine to return to the state after the user enters text or taps a button. Set this property to false if no user input is required (or expected), meaning that the System.CommonResponse component behaves like the System.Output component.

Set this property to true when setting a location.

Yes
autoNumberPostbackActions This property is used for composite bags, text responses, card responses. When set to true, this option prefixes numbers to options. Even when you haven’t set this option to true, auto-numbering can be enforced on card items when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true. As demonstrated by its default configuration, channel-specific auto-numbering can be applied to any skill bot that registered to a digital assistant (${(system.message.channelConversation.channelType=='twilio')?then('true','false')}): No
variable

This variable holds the name of the context or user variable that gets populated when a user responds by entering free text instead of tapping a button. This property is ignored when a user taps a button, because the button’s payload determines which variables values get set. If the variable property has already been set when the Dialog Engine enters this state, then the state is skipped.

For composite bag entities, reference the composite bag entity variable. Users get prompted for the individual entity values in the bag. When all the entity values are set, the System.CommonResponse component transitions to the next state.

No
nlpResultVariable Sets the variable property with an entity value (when that entity value hasn’t already been set for the referenced variable). You can enable nlpResultVariable to return value when you define it using a variable that holds the NLP results (such as iresult: "nlpresult" that’s used in our sample bots). By doing this, the nlpResultVariable property can still populate the value when it’s null if it finds a resolved entity that matches the one referenced by the variable. The dialog transitions to the next state when the nlpResultVariable sets the value. You can use this property in place of the System.SetVariable component. No
maxPrompts Before the System.CommonResponse component can populate the variable value that you’ve specified for the variable property from the text entered by the user, it validates the value against the variable type. This can be entity-type validation, or in the case of a primitive type, it’s a value that can be coerced to the primitive type.

When the component can’t validate the value, the Dialog Engine sends the message text and options again. (You can modify this message to reflect the validation failure.) To avoid an endless loop resulting from the user’s continued inability to enter a valid value, use this property to set a limit on the number of attempts given to the user. When the user exceeds this allotment, the System.CommonResponse component transitions to the cancel action. See Limiting the Number of User Prompts.

As described in Create a Composite Bag Entity, individual entities in the composite bag can override this setting when the Maximum User Input Attempts option is set.

No
keepTurn The keepTurn property only applies when you set the processUserMessage property to false. See System.Output to find out how to set this property. No
translate Use this property to override the boolean value that you’ve set for the autotranslate context variable. If you haven’t set this variable, or if you set it to false, then you can set this property to true to enable autotranslation for this component only. If you set the autotranslation variable is set to true, you can set this property to false to exclude this component from autotranslation. See Translation Services. No
footerText Enhances the output on text-only channels. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. No
transitionAfterMatch A boolean that, when you set it to true, enables a temporary transition from the entity matching performed by this component to a custom component. No
cancelPolicy Determines the timing of the cancel transition:
  • immediate—Immediately after the value set for the bag item’s Maximum User Input Attempts has been met. If this value has not been set, then the component fires this transition when the component-wide maxPrompts value has been met.

  • lastEntity—When the last entity in the bag has been matched with value.

No
The Metadata Property
You define the metadata at two levels for the System.ComponentResponse component: at the root level, where you define the output and actions that are specific to the System.CommonResponse component itself, and at the response level, where you define the display and behavior particular for the text, list, card, or attachment messages that this component outputs.
  AskLocation:
    component: "System.CommonResponse"
    properties:
      processUserMessage: "true" 
      variable: "location"
      metadata:
        responseItems:
        - text: "To which location do you want the pizza to be delivered?"
          type: "text"
          name: "What location"
          separateBubbles: true
        globalActions:
        - label: "Send Location"
          type: "location"
          name: "SendLocation"      
Property Description Required?
responseItems A list of response items, each of which results in a new message sent to the chat client (or multiple messages when you set iteration for the response item using the iteratorVariable property). Define these response items using these values:
  • text—Text bubbles (the text property) that can include a list of buttons that typically display as buttons.

    For composite bag entities (meaning the variable property names a composite bag entity variable), you can use a FreeMarker expression prompt for a value for the current entity ( “${system.entityToResolve.value.prompt}”).

  • cards—A series of cards that scroll horizontally or vertically.

  • attachment—An image, audio, video, or file attachment that user's can upload or download.

Yes
globalActions A list of global actions, meaning that they are not specific to any of the response items. These actions typically display at the bottom of the chat window. In Facebook Messenger, for example, these options are called quick replies. No
keywords A list of keywords that match the keywords entered by a user to a corresponding postback payload. Keywords support text-only channels where action buttons don't render well. No
You also configure the metadata for the various response items, such the text, card, or attachment messages.
Property Description Required?
type The type of response item that determines the message format. You can set a message as text, attachment, or cards. Yes
name A name for the response item that’s used internally, It’s not used at runtime. No
iteratorVariable

Dynamically adds multiple text, attachment, or keyword items to the response by iterating through the variable elements.

No
visible Determines how messages display per user input and channel. See Display Properties. No
rangeStart If you’ve specified an iteratorVariable, you can stamp out a subset of response items by specifying the rangeStart property in combination with the rangeSize property. You can enter a hardcoded value or use a FreeMarker expression that references a context variable that holds the range start. By using a rangeStart variable, you can then page to the next set of data by setting the rangeStart variable in the payload of the browse option. You can see an example of the rangeStart and rangeSize properties in the CrcPizzaBot’s OrderPizza state. No
rangeSize The number of response items that will be displayed as specified by the iteratorVariable and rangeStart properties. No
channelCustomProperties A list of properties that trigger functions that are particular to a channel. Because these functions are platform-specific, they’re outside of the System.CommonResponse component and as such, can’t be controlled by either the component’s root-level or response item-level properties. You can find an example of this property in the CrcPizzaBot’s OrderPizza state.
channelCustomProperties:
          - channel: "facebook"
            properties:
              top_element_style: "large"
For details on using channelCustomProperties, as well as the available properties for each channel, see Channel-Specific Extensions.
No
Keyword Metadata Properties
You can create shortcuts for actions by defining the keyword and label properties. For example, they allow users to enter S for Small.

The following snippet illustrates how a set of keywords get generated from the pizzaSize variable, which holds the list of values defined for the PizzaSize entity.
  askSize:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      keepTurn: false
      variable: "pizzaSize"
      nlpResultVariable: "iResult"       
      metadata: 
        responseItems:         
        - type: "text"  
          text: "What size of pizza do you want?" 
          actions: 
          - label: "(${enumValue[0]?upper_case})${enumValue?keep_after(enumValue[0])}"
            type: "postback"
            keyword: "${enumValue[0]?upper_case},${(enumValue?index)+1}"
            payload: 
              variables: 
                pizzaSize: "${enumValue}" 
            iteratorVariable: "pizzaSize.type.enumValues" 
    transitions: 
      next: "confirmOrder" 
Property Description Required?
keyword A list of keywords that trigger the postback payload that's defined by the payload property. You can use a FreeMarker expression to return keywords that the interatorVariable property generates from value list entities using the type and enumValues variables (iteratorVariable: "pizzaSize.type.enumValues"). For example, keyword: "${enumValue[0]?upper_case}${enumValue[1]?upper_case},${(enumValue?index)+1}" Yes
label The label for the action, which can be a text string or an Apache FreeMarker expression. For example, an expression that indicates a two-letter keyword is as follows:

label: "(${enumValue[0]?upper_case}${enumValue[1]?upper_case})${enumValue?keep_after(enumValue[1])}"

For multi-language support, use an Apache FreeMarker expression that references a resource bundle.
No
skipAutoNumber Set to true to suppress the auto-numbering for a key item when Enable Auto Numbering on Cards is set at either the Digital Assistant or the skill level. No
visible Determines how text messages display per user input and channel. See Display Properties No
iteratorVariable Dynamically adds multiple keywords by iterating over the items stored in the specified variable. For example, iteratorVariable: "pizzaSize.type.enumValues". No
payload The postback payload, which has the following properties.
  • action—The target action.
  • <variable names>—Sets values for a context or user variable.
You need to define at least one of these properties. See The payload Properties.
 
Display Properties
Set the display according to the user input and channel using the optional visibilty property.
Property Description Required?
expression The Apache FreeMarker directive that conditionally shows or hides text, card or attachments. For example, the CrcPizzaBot’s OrderPizza state uses "<#if cardsRangeStart?number+4 <pizzas.value?size>true<#else>false</#if>" No
channels:
 include:
 exclude:
For include and exclude, enter a comma-separated list of the channel types for which the text, card, or attachment should be shown (include) or hidden (exclude). The valid channel values are:
  • facebook

  • webhook

  • web

  • android

  • ios

  • twilio

  • kakaotalk

  • test

channelTest:
  component: "System.CommonResponse"
  properties:
    processUserMessage: false
    metadata:
      responseItems:
      - type: "text"
        text: "This text is only shown in Facebook Messenger"
        visible:
          channels:
            include: "facebook"             
      - type: "text"
        text: "This text is NOT shown in Facebook Messenger and Twilio"
        visible:
          channels:
            exclude: "facebook, twilio"
        actions:
        - label: "This action is only shown on web channel"
          type: "postback"
          payload:
            action: "someAction"
          visible:
            channels:
              include: "web"
No
onInvalidUserInput A boolean flag that shows the text item or attachment either when the user enters valid input (value=false) or when the user enters input that’s not valid (value=true). No
The Action Metadata Properties

You can define actions for a card or lists, a response type, or global actions for a component (such as Facebook's quick reply actions). You can't configure actions for attachment messages.

Property Description Required?
type The action type:
  • postback—Returns a string or JSON object. The returned content depends on the component. For the System.CommonResponse component, the postback returns a JSON object that contains the state, action, and variables.

  • share—Opens a share dialog in the messenger client, enabling users to share message bubbles with their friends.

  • call—Calls the phone number that’s specified in the payload.

  • url—Opens the URL that’s specified in the payload in the browser. For Facebook Messenger, you can specify thechannelCustomProperties property with webview_height_ratio, messenger_extensions and fallback_url.

  • location—Sends the current location. On Facebook Messenger, current location is not supported for text or card responses. It’s only supported using a Quick Reply. For more information, see the Facebook Messenger Platform documentation.

Yes
label A label for the action. To localize this label, you can use a FreeMarker expression to reference an entry in your bot’s resource bundle. Yes
iteratorVariable This option to adds multiple actions by iterating over the items stored in the specified variable. You can’t use this property with the share and location actions. No
imageUrl The URL of image used for an icon that identifies and action. You can use this property to display an icon for the Facebook quick reply button (which is a global action). No
skipAutoNumbering When set to true, this property excludes an individual postback action from having auto-numbering applied to it. You can use this property for a text or card response. No
channelCustomProperties A list of properties that some trigger channel-specific functionality that isn’t controlled by the standard action properties. You can find an example in the CrcPizzaBot’s OrderPizza state. No
name A name that identifies the action on the Digital Assistant platform. This name is used internally and doesn’t display in the message. No
visible Determines how attachments display per user input and channel. See Display Properties. No
payload A payload object for the call, url, and postback response items. See The payload Properties. No
The payload Properties
Property Description Required?
action An action transition that gets triggered when user chooses this action. No
variables Sets the values for user or context variables when you set the action type to postback and add payload properties that are named for the context or user variables. When the user taps the action, the variables are set to the values specified by this property. No
url The URL of the website that opens when users tap this action. This property is required for the url action type.
phoneNumber The phone number that's called when a user taps this action. This property is required for the call action type.
How Do Non-Postback Actions Render on Text-Only Channels?

Some things to note for these action metadata properties for the System.CommonResponse component.

  • If the text-only channel supports hyperlinks, you can use them in place of buttons when the global action type is url or call.

  • The share and location action types will be ignored or won’t render.

Tip:

Non-postback actions like url and call can’t be numbered, because they don’t get passed to the Dialog Engine and therefore can’t get triggered by keywords. Consequently, if you mix the two types of actions, your bot’s message can look inconsistent because only some options get numbered.
A runtime image of non-postback and postback numbering.
You can create more consistent output by disabling auto-numbering for a postback action by configuring the postback action with an if directive and the skipAutoNumber property:
{
  "type": "text",
  "text": "Please choose one of the following options",
  "actions": [
    {
      "type": "url",
      "label": "Check out our website",
      "url": "http://www.oracle.com"
    },
    {
      "type": "postback",
      "label": "<#if autoNumberPostbackActions.value>Enter 1 to Order pizza<#else>Order Pizza<#if>"
      "skipAutoNumber": true
      "keyword": "1"
      "postback": { ...}
    }
  ]
}

The Text Response Item

After you add a textResponse state to your dialog flow, you can rename it and then either replace the placeholder properties with your own definitions, or delete the ones that you don’t need. The Common response-text template describes two types of text response messages: simple text and text with actions.

If you want to see an example of text response with actions, take a look at the CrcPizzaBot’s showMenu state: Because it names postback as an action, it enables the skill to handle unexpected user behavior, like selecting an item from an older message instead of selecting one from the most recent message.
context:
  variables:
...
    numberKeywords: "string"

...

  LoadNumberKeywords:
    component: "System.SetVariable"
    properties:
      variable: "numberKeywords"
      value:
        - keywords: "first,1st,one"
        - keywords: "second,2nd,two"
        - keywords: "third,3rd,three"
        - keywords: "fourth,4th, four"
        - keywords: "fifth,5th, five"
    transitions: {}

...
    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"
Property Description Required?
text The text that prompts the user. Yes
iteratorVariable Dynamically adds multiple text items to the response by iterating over the items stored in the variable that you specify for this property. Although you define the variable as a string, it holds JSON array when it’s used as an iterator variable. You can reference properties in an object of the array with an expression like ${iteratorVarName.propertyName}. For example, with an iterator variable named pizzas, the name property of a pizza can be referenced using the expression ${pizzas.name}. No
footerText Text that displays at the bottom of the message (below both the text and button actions, if any). Add a footer to enhance the output on text-only channels. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. No
separateBubbles You can define this property if you also define the iteratorVariable property. When you set this property to true, each text item is sent as separate message, like Pizzas and Pastas in the CrcPizzaBot’s ShowMenu and OrderPizza states. If you set it to false, then a single text message is sent, one in which each text item starts on a new line. No
visible Determines how text messages display per user input and channel. See Display Properties. No
actions The postback action. For text-only support, you can define keywords. No
The Card Response Item

Like the textResponse state, you can rename the cardResponse state that’s added to your dialog flow and then update the properties with your own definitions. Specifically, you can configure a card response item by defining the following properties. You can delete the properties that you don’t need.

Property Description Required?
cardLayout The card layout: horizontal (the default) and vertical. Yes
headerText Header text. For example: headerText: "<#if cardsRangeStart?number == 0>Here are our pizzas you can order today:<#else>Some more pizzas for you:</#if>" . No
title The card title Yes
description The card description, which displays as a subtitle. No
imageUrl The URL of the image that displays beneath the subtitle. No
cardUrl The URL of a website. It displays as a hyperlink on the card, which users tap to open. No
iteratorVariable Dynamically adds multiple cards to the response by iterating over the items stored in the variable that you specify for this property. Although you define the variable as a string, it holds a JSON array when it’s used as an iterator variable. You can reference properties in an object of the array with an expression like ${iteratorVarName.propertyName}. For example, with an iterator variable named pizzas, the name property of a pizza can be referenced using the expression ${pizzas.name}. No
rangeStart If you’ve specified an iteratorVariable, you can stamp out a subset of cards by specifying the rangeStart property in combination with the rangeSize property. You can enter a hardcoded value or use a FreeMarker expression that references a context variable that holds the range start. Using a rangeStart variable, you can then page to the next set of data by setting the rangeStart variable in the payload of a browse option. No
rangeSize The number of cards that will be displayed as specified by the iteratorVariable and rangeStart properties. No
visible Determines how action labels rendere per user input and channel. See Display Properties. No

You can assign a set of actions that are specific to a particular card, or a list of actions that are that are attached to the end of the card list.

The CrcPizzaBot’s OrderPizza state includes a card response item definition, as shown in the following snippet:
cards:
          - title: "${pizzas.name}"
            description: "${pizzas.description}"
            imageUrl: "${pizzas.image}"
            name: "PizzaCard"
            iteratorVariable: "pizzas"
            rangeStart: "${cardsRangeStart}"
            rangeSize: "4"
            actions:
            - label: "Order Now"
              type: "postback"
              payload:
                action: "order"
                variables:
                  orderedPizza: "${pizzas.name}"
                  orderedPizzaImage: "${pizzas.image}"
              name: "Order"
The Attachment Response Item

The attachmentResponse state includes the following properties.

Property Description Required?
attachmentType The type of attachment: image, audio, video, and file. Yes
attachmentURL The attachment’s download URL or source. Yes
The CrcPizzaBot’s Confirmation state uses an attachment response item to display picture of the order, one that’s different from the item pictured in the menu.
  Confirmation:
    component: "System.CommonResponse"
    properties:
      metadata:
        responseItems:
        - text: "Thank you for your order, your ${pizzaSize} ${orderedPizza} pizza\
            \ will be delivered in 30 minutes at GPS position ${location.value.latitude},${location.value.longitude}!"
          type: "text"
          name: "conf"
          separateBubbles: true
        - type: "attachment"
          attachmentType: "image"
          name: "image"
          attachmentUrl: "${orderedPizzaImage}"
      processUserMessage: false
The system.entityToResolve Variable
The system.entityToResolve variable tracks an entity value. You can use it to define the logic for an entity's error message, or for various properties that belong to the System.resolveEntities and System.CommonResponse components. Append the following properties to return the current entity value:
  • userInput
  • prompt
  • promptCount
  • udpdatedEntities
  • outOfOrderMatches
  • disambiguationValues
  • enumValues
  • needShowMoreButton
  • rangeStartVar
  • nextRangeStart
Here's an example of using this variable to return the current user input in an entity's error message:
Sorry,'${system.entityToResolve.value.userInput!'this'}' is not a valid pizza size.
Here's an example of using various system.entityToResolve definitions. Among these is a message defined for the text property, which confirms an update made to a previously set entity value using an Apache FreeMarker list directive and the updatedEntities property.
    metadata:
      responseItems:        
      - type: "text" 
        text: "<#list system.entityToResolve.value.updatedEntities>I have updated <#items as ent>${ent.description}<#sep> and </#items>. </#list><#list system.entityToResolve.value.outOfOrderMatches>I got <#items as ent>${ent.description}<#sep> and </#items>. </#list>"
      - type: "text" 
        text: "${system.entityToResolve.value.prompt}"
        actions:
        - label: "${enumValue}"
          type: "postback"
          iteratorVariable: "system.entityToResolve.value.enumValues"
For global actions, this variable controls the Show More global action with the needShowMoreButton, rangeStartVar, and the nextRangeStart properties:
        globalActions: 
        - label: "Show More"
          type: "postback" 
          visible:
            expression: "${system.entityToResolve.value.needShowMoreButton}"
          payload:
            action: "system.showMore"
            variables: 
              ${system.entityToResolve.value.rangeStartVar}: ${system.entityToResolve.value.nextRangeStart} 
        - label: "Cancel"
          type: "postback" 
          visible:
            onInvalidUserInput: true
          payload:
            action: "cancel"
The Show More label must include a system.showMore (action: "system.showMore"). Otherwise, it won't function.
User Message Validation
The System.CommonResponse, System.Text, and System.List components validate the user-supplied free-text value that gets set for the variable property. For example, when the variable property is defined as a primitive type (string, boolean, float, double), these components try to reconcile the value to one of the primitive types. When the variable property is defined for an entity-type variable, these components call the NLP Engine to resolve the value to one of the entities. But when these components can’t validate a value, your bot can display an error message. By referencing the system.invalidUserInput variable, you can add a conditional error message to your bot’s replies. This variable is a boolean, so you can use it as a condition with the FreeMarker if directive to display the message only when a user enters an invalid value. Otherwise, the message is hidden. The CrcPizzaBot’s AskPizzaSize state in the following snippet demonstrates this by adding this variable as condition within a FreeMarker template that’s evaluated by the if directive. Because it’s set to true, the bot adds an error message to the standard message (What size do you want?) when the user enters an invalid value.
  AskPizzaSize:
    component: "System.CommonResponse"
    properties:
      variable: "pizzaSize"
      nlpResultVariable: "iresult"
      maxPrompts: 2
      metadata:
        responseItems:
        - type: "text"
          text: "<#if system.invalidUserInput == 'true'>Invalid size, please try again.\
            \ </#if>What size do you want?"
          name: "What size"
          separateBubbles: true
Transition Actions
You can use these transtions for the System.CommonResponse, System.List, and System.Text components.
Action Description
cancel The component triggers this action when user enter invalid input or when they exceed the alloted attempts set by the maxAttempts property.
textReceived The component triggers this action when a user enter text or an emoji.
attachmentReceived The component triggers this action when user upload image, audio, video, or file attachments,
locationReceived The component triggers this action when users enter their geolocation.
System.outOfOrderMesage Used for out-of-order messages. The component triggers this response when users don't tap the actions in the current message from the bot, but instead tap an option in a prior message. See Configure the Dialog Flow for Unexpected Actions.

System.Webview

The System.Webview component opens a webview within your skill, or for skills that run in a web channel, in an browser tab.

System.WebView Component Properties
Property Description Required?
sourceVariableList A comma-separated list of context or user variable names. These variable names are the parameters that are sent to the webview; they’re the input parameters from your bot. You can set each variable by adding a series of System.SetVariable states before the System.Webview state. Yes
variable The name of the variable (a string value) that identifies the webview payload that’s returned to the bot after the user completes his or her interactions within the webview.

Because the payload is stored in this variable, which you can access at a later point in your dialog flow definition. For example, you can reference this in an output component.

Yes
prompt A text string like “Tap to continue.” No
service The name of the webview component service. No
imageUrl
The URL to the image that accompanies a prompt. No
linkLabel The label for the button that invokes the web app. No
cancelLabel The label for the Cancel button that lets users leave the state without invoking the web app. No
autoNumberPostbackActions Enables user input in SMS channels, which don’t support buttons, by adding number equivalents to the UI elements.
  • false—Overrides the global autoNumberPostbackActions variable.

  • true

    Prefixes the Cancel button with a sequence number, which when entered, executes the button postback payload as if the user tapped the button rather than enter its number equivalent.
No
translate Use this property to override the boolean value that you’ve set for the autotranslate context variable. If you haven’t set this variable, or if you set it to false, then you can set this property to true to enable autotranslation for this component only. If you set the autotranslation variable is set to true, you can set this property to false to exclude this component from autotranslation. See Translation Services. No
Transitions for the System.Webview Component
Transitions Description
next Names the next state in the dialog flow after the successful callback from the web app.
return Exits the convesation after the successful callback from the web app.
error Names the state that handles errors.
actions
  • cancel—Names the state that handles the "user taps cancel" scenario.
  • textReceived—Names the state that handles the scenario where user enter text instead of tapping a button.

System.ResolveEntities

Iterates through all the entity fields in the composite bag, converses with the user and resolves all the fields. The component randomly chooses the prompts that you provide for each entity while resolving that entity.

Property Description Required
variable Refers to the composite entity context variable that’s populated by this component. If all child entities of the composite entity variable already have a value, then the dialog flow transitions to the next state without sending the user a message. Yes
nlpResultVariable Populates the variable property (which references the composite bag entity variable) using the values stored in the nlpresult context variable. You can define this property by naming the nlpresult variable (typically, iResult). When the framework resolves a single child entity, then the variable property gets populated with just that entity value. When the nlpresult variable holds values for all of the child entities, then the dialog flow transitions to the next state. You can use this property in place of the SetVariable states that populate the child entity values. No
maxPrompts Specifies the number of attempts allotted to the user to enter a valid value that matches the child entity type. If the maximum number of attempts is exceeded for the first child entity, this property resets to 0 and the bot outputs the prompt for the next child entity. As described in Create a Composite Bag Entity, individual entities in the composite bag can override this setting when the Maximum User Input Attempts option is set. No
autoNumberPostbackActions When you set to true, this option prefixes numbers to options. Even when you haven’t set this option to true, auto-numbering can be enforced on list items when the digital assistant’s Enable Auto Numbering on Postback Actions configuration is set to true. Channel-specific auto-numbering can be applied to any skill bot that's registered to a digital assistant:
${(system.message.channelConversation.channelType=='twilio')?then('true','false')}
No
footerText Enhances the output on text-only channels. As described in Footers, you can use FreeMarker expressions to conditionalize the footer text for text-only channels. No
headerText A message that displays before the component prompts the user for the next item in the bag. You can use this header to provide feedback on the previous entities in the bag that have been matched (or updated).
headerText: "<#list system.entityToResolve.value.updatedEntities>I have updated <#items as ent>${ent.description}<#sep> and </#items>. </#list><#list system.entityToResolve.value.outOfOrderMatches>I got <#items as ent>${ent.description}<#sep> and </#items>. </#list>"
No
transitionAfterMatch A boolean that, when you set it to true, enables a temporary transition from the entity matching performed by this component to a custom component. By default, this is false. No
cancelPolicy Determines the timing of the cancel transition:
  • immediate—Immediately after the allotted maxPrompts attempts have been met for an entity in the bag.

  • lastEntity—When the last entity in the bag has been matched with a value.

No

Transitions

The System.CommonResponse , System.List, and System.Text components use these transitions. Message Handling for Output Components describes how these transitions get triggered.
Transition Description
cancel Set this transition when a user exceeds the allotted attempts set by the maxAttempts property, or redirect the flow .
textReceived Set this when users send text or emojis instead of tapping an action button or the link that launches an webview. In the following snippet, textReceived redirects the flow to the System.Intent component (the intent state) so that the bot can attempt to resolve the unexpected user input to one of its intents.
  ShowMenu:
    component: "System.CommonResponse"
    ...
      processUserMessage: true
    transitions:
      actions:
        pizza: "OrderPizza"
        pasta: "OrderPasta"
        textReceived: "Intent"
attachmentReceived Set this when a user sends an image, audio, video, or file attachment.
locationReceived Set this when the user sends a location.
system.outOfOrderMessage Set this to circumvent unexpected user behavior. Specifically, when a user doesn’t tap an action item in the current message, but instead taps an action belonging to an older message in the chat session.
Composite Bag Transitions
These System.CommonResponse components triggers the match and cancel actions based the values matched from the user input and on your configuration of the transitionAfterMatch and cancelPolicy properties.
Action Description Required?
match The component triggers this action to navigate to the specified state when:
  1. At least one entity in the bag has matched the user input.

  2. When you set the transitionAfterMatch property to true, meaning that certain processing can temporarily take place outside of the System.CommonResponse component.

No
cancel The component triggers this action to navigate to the specified state based on the setting for the cancelPolicy property. No

Footers

Use footers in System.List and System.CommonResponse for additional user guidance when your bot runs on text-only channels..
Runtime image of footer text.
This footer displays on all channels, even ones that support buttons like Facebook. However, you can configure channel-specific rendering for the footer. To do this:
  • Define the autoNumberPostbackActions variable using the system.message expression.
    setAutoNumbering:
      component: "System.SetVariable"
      properties:
        variable: "autoNumberPostbackActions" 
        value: "${(system.message.channelConversation.channelType=='facebook')?then('true','false')}" 
  • Define the footerText definition with an Apache FreeMarker if directive to display or hide the footer based on the channel type.
    footerText: <#if autoNumberPostbackActions.value>"Make your choice by entering the menu option number."</#if>
Note

On Facebook, the System.CommonResponse renders the footer text in its own text bubble that appears just before the global actions (the quick replies). The footer can’t display after these actions, because that requires a second footer text bubble that causes the actions to disappear.

Message Handling for Output Components

Typically, a user might respond to a message in the following ways:
  • By entering free text.

  • By sending their location.

  • Using a multi-media option to send an image, audio file, video, or file attachment.

  • Tapping one of the postback buttons displayed in the most recent message output by the bot.

  • By scrolling to a previous message in the conversation and tapping one of its buttons.

Handling Free Text
When a user enters free text, the System.CommonResponse, System.List and System.Text components first validate the value. For valid values, the components trigger the textReceived transition. If you don’t define this transition, then the Dialog Engine transitions to the next state, or performs the default transition.

Tip:

Use textReceived to handle unexpected user messages when you expect the user to tap a button, send an attachment, or a location.
Handling Multimedia Messages
When a users sends a file, image, video, or audio file, the System.CommonResponse, System.List, and System.Text component stores the attachment information as a JSON object in the variable property that’s specified for the component. This object has the following structure:
{
  "type": "video",
  "url": "https://www.youtube.com/watch?v=CMNry4PE93Y"
}
For example, if a video attachment is stored in a variable called myVideo, you can access the video using the FreeMarker expression, ${myVideo.value.url}. It also sets the transition action to attachmentReceived. You don’t have to specify this transition in your OBotML definition. If you don’t define this transition, then the Dialog Engine transitions to the next state, or performs the default transition.

Tip:

Use attachmentReceived to handle situations where users send an attachment unexpectedly.
Handling Location Messages
When a user sends his or her current location, the System.CommonResponse, System.List, and System.Text components store the location information as a JSON object in the variable property specified for the component. This object has the following structure:
{
  "title": "Oracle Headquarters",
  "url": "https://www.google.com.au/maps/place/…",
  "longitude": -122.265987,
  "latitude": 37.529818
}
For example, if the location is stored in a variable called location, you can access the latitude using the FreeMarker expression, ${location.value.latitude}. It also triggers the locationReceived action, so you don’t have to specify this transition in your OBotML definition. If you don’t define this transition, then the Dialog Engine transitions to the next state, or performs the default transition.

Tip:

Include locationReceived transition to handle situations where users send a location unexpectedly, or when you want to ensure that a user sends a location at the point where it’s expected.
Postback Actions
The actions in the response message, such as buttons, links, and list items, are implemented as postback actions. For example, when a user taps a button, it's postback gets rendered. Its payload is a JSON object that holds the name of the state, the values set for the user and context variables, and the transition actions. For example, the following payload is rendered when a user taps the Order Now button for a pepperoni pizza:
{
	"action": "order",
	"state": "OrderPizza",
	"variables": {
		"orderedPizza": "PEPPERONI",
		"orderPizzaImage": "http://pizzasteven/pepperoni.png"
	}
How Does Digital Assistant Detect Unexpected Actions?
The system.state property in the payload, which identifies the state for which the postback was rendered, enables the system to identifiy when a user performs an action that occurs out of the current scope, such as tapping a button from a previous response.

        "system.postbackActions": {
          "small": {
            "postback": {
              "variables": {
                "size": "Small"
              },
              "system.botId": "44F2405C-F317-4A3F-8250-617F54F01EA6",
              "action": "Small",
              "system.state": "size"
For example, a user might tap the Order Now button for a pepperoni pizza, but instead of completing the order, he might scroll further up to a previous message and clicks Order Now for a pasta dish.

At this point, the system compares the system.state property in the payload of the incoming postaback action against the current state. When the two no longer match, the skill executes a transition that can, depending on how you configure your dialog flow, either honors the user's request, or denies it.

By default, Digital Assistant allows out-of-order actions. This means that the variable values get reset. Using the system.outOfOrderMessage action and the system.actualState and system.ExpectedState variables, you can customize this behavior either for the entire skill, or for a pariticular state in the dialog flow.
  • system.actualState—Holds the value of the state property in the incoming postback payload, the "out-of-order" message.

  • system.expectedState—Holds the value of the current state.
    Note

    Only components that set the state property in the postback payload can enable the skill to respond when the user skips back in the flow. The SystemOAuthAccountLink does not set this property.
Override Out-of-Order Message Handing for Certain States
You don't need to change the default behavior when you want your skill to always support out-of-order actions. However, depending on the context in which values get set, you may need to override this behavior for some states in the dialog flow. To enable out-of-order message handling as default behavior except when configured otherwise by individual states, set the the out-of-order handling as a global transition. You can set this transition with "${system.actualState}":
defaultTransitions:
  actions:
    system.outOfOrderMessage: "${system.actualState}"
When the Dialog Engine detects the out-of-order postback action, it checks for a system.outOfOrderMessage transition definition in the current state. If the state doesn't include this action, then the Dialog Engine executes this global transition and moves back to the state named in the out-of-order postback action payload.
askFromAccountType:
  component: "System.List"
  properties:
    options: "${accountType.type.enumValues}"
    prompt: "From which account do you want to make a payment?"
    variable: "accountType"
  transitions:
    next: "askToAccount"
    actions:
      system.outOfOrderMessage: "noLongerSupported"
noLongerSupported:
  component: "System.Output"
  properties:
    text: "Sorry, this option is no longer supported, please start over"
  transitions:
    return: "done"
Override Out-of-Order Message Handling with a Message Handling State

You can also change the default behavior by setting the value for the system.outOfOrderMessage action to a state that handles the out-of-order actions:
...

defaultTransitions:
  actions:
    system.outOfOrderMessage: "startOutOfOrderMessageHandling"
...
states:
  startOutOfOrderMessageHandling:
    component: "System.Switch"
    properties:
      source: "${system.actualState}"
      values:
      - "displayLocations"
      - "getVoucher"
    transitions:
      actions:
        displayLocations: "saveOutOfOrderValue"
        getVoucher: "invalidOperation"
        NONE: "${system.actualState}"  
  invalidOperation:
    component: "System.Output"
    properties:
      text: "Sorry. The option you selected is no longet available."
    transitions:
      return: "done"
  saveOutOfOrderValue:
    component: "System.SetVariable"
    properties:
      variable: "_tmpOutOfOrderValue"
      value: "${system.message.messagePayload.postback.variables.location}"
    transitions:
      next: "outOfOrderMessageHandler"
 outOfOrderMessageHandler:
    component: "System.List"
    properties: 
      prompt: "What do you want to do?"
      options: 
      - label: "Proceed with Selected Action"
        value: "continueOutOfOrderFlow" 
      - label: "Ignore Selected Action"
        value: "continueCurrentFlow" 
    transitions:
      actions:
        continueOutOfOrderFlow: "continueOutOfOrderFlow"
        continueCurrentFlow: "${system.expectedState}"
...

Tip:

Check out this article for strategies on handling out-of-order actions.

Limiting the Number of User Prompts

The maxPrompts property limits the number of times that the output components can prompt the user when they can’t match the input value to any of the values defined for the entity or input type that’s referenced by the variable property. While this is an optional property, adding it can prevent your dialog from going in circles when users repeatedly enter invalid values. You can set the maximum number of prompts using an integer (like 2 in the following snippet). The dialog moves onto the next state if the user enters a valid value before reaching this limit. Otherwise, the dialog transitions to the state defined by the cancel action. In the following sample, the dialog moves to the setDefaultSize state when users run out of chances. At this point, the bot makes their choice for them, because the System.SetVariable component sets the pizza size to large.

  size:
    component: "System.List"
    properties:
      prompt: "What size Pizza do you want?"
      options: "${size.type.enumValues}"
      variable: "size"
      maxPrompts: 2
    transitions:
      actions:
        cancel: "setDefaultSize"
  setDefaultSize:
    component: "System.SetVariable"
    properties:
      variable: "size"
      value: "Large"
    transitions: {}
Note

Setting the maxPrompts property to a negative number is same as not entering a value, or not including the property at all: the bot will continue to prompt the user until it receives a valid value.

The translate Property

The user interface and input components all have a translate property that overrides the global autoTranslate variable setting:
  • If you set the autoTranslate variable to false (the default), then no autotranslation occurs on the component unless you set the translate property to true.

  • If you set the autoTranslate variable to true, then the translate property is implicitly set to true as well, which means that the label, title, description, prompt and text strings will be translated.

For example, If you enabled autotranslate by setting it to true, then setting a component’s translate property to false excludes its prompt, title, description, label and text strings from translation. Conversely, if you don’t enable autotranslate, but a component's translate property is set to true, then the component’s prompt, title, description, label, and text string is translated into the detected user language using the configured translation service. (Input components translate the user input into English.)
autoTranslate is set to... ...and the component’s translate property is set to... ...then the user input, prompt, label, text, title, and description get translated
true not set yes
true true yes
true false no
false not set no
false false no
false true yes

Variable Components

System.SetVariable

The System.SetVariable component sets the value of a pre-defined variable. For example, you can set the value for an entity variable because this component can extract the entity match that's held by the iResult variable that's set for the System.Intent component.

Property Description Required?
variable The name of the variable that’s defined as one of the context properties. This can be a variable defined for an entity or a predetermined value, like a string. Yes
value The target value, which you can define as a literal or as a expression that references another variable.
Use dot notation to specify a value of an item in a composite bag entity variable that’s been declared as a context variable (expense in the following example).
setExpenseType:
  component: "System.SetVariable"
  properties:
    variable: "expense.Type"
    value: "Flight"
  transitions:
    next: "resolveExpense"
Yes

The startTxns state in the following code snippet shows how you can define the target value using an expression that references another entity variable. In this case, "${iResult.value.entityMatches['AccountType'][0]” references the iResult variable that’s resolved earlier in the flow by the System.Intent component. This variable sets the accountType variable if the AccountType entity is associated with the intent that’s resolved by the System.Intent component. For example, if a user enters, “I want to transfer money to checking,” then this expression sets the accountType variable value to “checking.” If the System.SetVariable component can’t find matches, then the Dialog Engine moves on to the next state in the dialog flow (declared by transitions: {}).

main: true
name: "FinancialBotMainFlow"
context:
  variables:
    accountType: "AccountType"
    txnType: "TransactionType"
    txnSelector: "TransactionSelector"
    toAccount: "ToAccount"
    spendingCategory: "TrackSpendingCategory"
    paymentAmount: "string"
    iResult: "nlpresult"
states:

...

  startTxns:
    component: "System.SetVariable"
    properties:
      variable: "accountType"
      value: "${iResult.value.entityMatches['AccountType'][0]}"
    transitions: {}
...
Besides entity variables, you can set a predetermined value for a variable using an Apache FreeMarker expression or, as shown in the following snippet, a literal. You can find out more about FreeMarker here.
setOAuthRedirectURL:
    component: "System.SetVariable"
    properties:
      variable: "redirectURL"
      value: "https://thatcompany.io/connectors/v1/tenants/5c824-45fd-b6a2-8ca/listeners/facebook/channels/78B5-BD58-8AF6-F54B141/redirect"
    transitions: {}
See System.OAuthAccountLink

System.ResetVariables

This component resets the values of the variables to null.

This component doesn’t require any transitions, but you can, for example, set a transition back to a System.Intent state to allow users to input new values.
Property Description Required?
variableList A comma-separated list of variables that need to be reset.
Use dot notation to reset the value of a specific bag item in the composite bag, which is declared a context variable (expense in the following example).
resetExpenseType:
  component: "System.ResetVariables"
  properties:
    variableList: "expense.Type"
  transitions:
    next: "resolveExpense"
Yes

System.CopyVariables

Copies the variable values.

Define this component using from and to properties as in the following snippet, where the value is copied to a user context:
setupUserContext:
    component: "System.CopyVariables"
    properties:
      from: "lastQuestion,lastResponse"
      to: "user.lastQuestion,user.lastResponse"
This component needs both of these properties, but their definitions don’t have to mirror one-another. While you can define both from and to as lists of variables, you can also define from with a single variable and to as a list. If you set an additional to property, it inherits the variable value of the proceeding from property.