The Metadata Property in Common Response Components

You use the Metadata property in Common Response components to define how messages will be displayed to users.

You define the metadata at two levels: at the root level, where you define the output and actions that are specific to the 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.
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 or a combination of the iteratorVariable and iteratorExpression properties). 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 users can upload or download.

  • editForm—An interactive form.
  • form
  • dataSet
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
iteratorExpression A FreeMarker expression used to display values from an array that is nested within the variable specified by the iteratorVariable property.

For example, if you have set the value of the iteratorVariable property to "team" and that variable has an element called members that you want to display the values of, you would use the expression ${team.value.members}.

No
visible Determines how messages display per user input and channel. See The visible Property. 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 Common Response 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.
Description of keywords_crc_list.png follows

The following snippet illustrates how you can have a set of keywords get generated from a pizzaSize variable that holds the list of values defined for a PizzaSize entity.
      
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"
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 properties (iteratorVariable: "pizzaSize.type.enumValues"). 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 The visible Property No
iteratorVariable Dynamically adds multiple keywords by iterating over the items stored in the specified variable. For example, iteratorVariable: "pizzaSize.type.enumValues". No
iteratorExpression A FreeMarker expression used to display values from an array that is nested within the variable specified by the iteratorVariable property.

For example, if you have set the value of the iteratorVariable property to "team" and that variable has an element called members that you want to display the values of, you would use the expression ${team.value.members}.

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.
 

Extract Keywords from Messages

While the component triggers a postback when users enter a number, you can extend your skill to support broader input like First, or let's try the 1st item. To do this, create an array variable for the keyword phrases (e.g. first,1st,one, second, 2nd, two, etc.)

Then reference the variable in the keyword property in the metadata. For example, this is what it might look like in a flow for ordering a pizza.
- keyword: "${pizzas.name},<#if pizzas?index <KEYWORDS_VAR.value?size>${numberKeywords.value[pizzas?index].keywords}</#if>,<#if pizzas?index==cardsRangeStart?number+[cardsRangeStart?number+3,pizzaCount.value?number-cardsRangeStart?number-1]?min>last</#if>"
In this definition, the last keyword is based on the current range start. It's set to the last pizza currently display, based on the number of times that the customer has entered more.

The visible Property

Set the display according to the user input and channel using the optional visible 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 && textOnly=='false'>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

  • websdk

  • androidsdk

  • iossdk

  • twilio

  • slack

  • msteams

  • cortana

  • test

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: "websdk"
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
onDisambiguation When true, only shows the response item, card ,or action when a disambiguation prompt is shown. No
entitiesToResolve Use this property to create customized message for each composite bag item. Add a comma-delimited list of composite bag item names for which the response item should be shown (include) or hidden (exclude).
visible:
           entitiesToResolve:
           include: "Amount"
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 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
iteratorExpression A FreeMarker expression used to display values from an array that is nested within the variable specified by the iteratorVariable property.

For example, if you have set the value of the iteratorVariable property to "team" and that variable has an element called members that you want to display the values of, you would use the expression ${team.value.members}.

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 The visible Property. 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 Common Response components.

  • 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.
Using the SDK, you can create more consistent output by disabling auto-numbering for the postback. For example:
{
  "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

Here are the properties for text response items in Common Response components.

Property Description Required?
text The text that prompts the user. Yes
iteratorExpression A FreeMarker expression used to display values from an array that is nested within the variable specified by the iteratorVariable property.

For example, if you have set the value of the iteratorVariable property to "team" and that variable has an element called members that you want to display the values of, you would use the expression ${team.value.members}.

 
iteratorVariable Dynamically adds multiple text, attachment, or keyword items to the response by iterating through the variable elements. 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 The visible Property. No
actions The postback action. For text-only support, you can define keywords. No
If you want to see an example of text response with actions, take a look at the metadata for the CrcPizzaBot’s showMenu state:

Description of text_response_rt_output.png follows

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.
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"

The Card Response Item

Here are the properties for card response items in Common Response components.

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
iteratorExpression A FreeMarker expression used to display values from an array that is nested within the variable specified by the iteratorVariable property.

For example, if you have set the value of the iteratorVariable property to "team" and that variable has an element called members that you want to display the values of, you would use the expression ${team.value.members}.

 
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 The visible Property. 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:
responseItems:
  - type: "cards"
    headerText: "<#if cardsRangeStart?number == 0>Here are our pizzas you can order today:<#else>Some more pizzas for you:</#if>"
    cardLayout: "vertical"
    name: "PizzaCards"
    actions:
      - label: "More Pizzas"
        keyword: "more"
        type: "postback"
        skipAutoNumber: true
        visible:
          expression: "<#if cardsRangeStart?number+4 < pizzas.value?size && textOnly=='false'>true<#else>false</#if>"
        payload:
          action: "more"
          variables:
            cardsRangeStart: "${cardsRangeStart?number+4}"
        name: "More"
    cards:
      - title: "${(textOnly=='true')?then((pizzas?index+1)+'. ','')}${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"
            visible:
              expression: "${(textOnly=='true')?then('false','true')}"

How Do Cards Render on Text-Only Channels?

Common Response components render responses as cards. When your skill runs in a text-only channel, some of the card response item properties behave differently. Here are some things to keep in mind.

  • There is no vertical or horizontal scrolling (behaviors set by the cardLayout option). All cards render within a single message bubble, which can include a header and footer. The card title and description properties are separated by a new line character. You can number the card's title proprety.

  • Hyperlinks are still supported in text-only channels, with the address configured for cardUrl property rendered within the bubble along with the title and description properties, which are separated by new line character.

  • Images specified by the imageURL property are rendered.

  • The label text for action buttons displays (though the buttons themselves are not rendered). Users can enter the text, or, if auto-numbering is enabled, they can enter the corresponding number instead for added convenience.

Description of default_card_text_only.png follows

Optimize Cards on Text-Only Channels with Keywords

Most cards have a single action, such as the CRCPizzaBot's Order Now button and a global action like More for loading the next card in the carousel. As illustrated in How Do Cards Render on Text-Only Channels?, the label for each action gets auto-numbered when the skill runs on SMS/text-only channels. On these channels, a set of cards is represented in a single bubble, which can become long and therefore difficult to read. You can avoid this by configuring postback actions that aren't associated with the action labels, but are executed by user keywords (1,2,3, cheese, or more, for example).


Description of cards_text_only.png follows

You can hide the action labels when your skill runs on text-only channels using these general guidelines.

In the metadata property:
  • Define the keywords property. In the following CRCPizzaBot snippet, the ${pizza.name} expression set for the keyword property defines a keyword for each pizza name:
    
    metadata:
      keywords:
        - keyword: "${pizzas.name},<#if pizzas?index <numberKeywords.value?size>${numberKeywords.value[pizzas?index].keywords}</#if>,<#if pizzas?index==cardsRangeStart?number+[cardsRangeStart?number+3,pizzaCount.value?number-cardsRangeStart?number-1]?min>last</#if>"
          visible:
            expression: "${textOnly.value}"
    ...

    These keywords are only added when textOnly is true.

In the card metadata:
  • Define the title property. In the following snippet, an expression uses the FreeMarker index variable to prefix a number to the title (returned by ${pizzas.name} when the textOnly variable value is true). This means that when a customer enters more, the skill will load another message bubble containing the next set of pizzas starting at Number 5 (rangeSize: "4").
    cards:
            - title: "${(textOnly=='true')?then((pizzas?index+1)+'. ','')}${pizzas.name}"
              description: "${pizzas.description}"
              imageUrl: "${pizzas.image}"
              name: "PizzaCard"
              iteratorVariable: "pizzas"
              rangeStart: "${cardsRangeStart}"
              rangeSize: "4"
  • In the following snippet, the card actions ("Order" and "More Pizzas") are only displayed when the textOnly variable value is false:
            - label: "More Pizzas"
              keyword: "more"
              type: "postback"
              skipAutoNumber: true
              visible:
                expression: "<#if cardsRangeStart?number+4 < pizzas.value?size && textOnly=='false'>true<#else>false</#if>"
  • Add a footer that displays only when the textOnly variable value is true.
    footerText: "<#if textOnly=='true'>Enter a pizza number to make your choice<#if cardsRangeStart?number+4 < pizzas.value?size>, or type 'more' to see more pizzas</#if></#if>"

The Attachment Response Item

The attachment response item 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.
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}"

Field

A Field element contains the following properties:
Name Description Type Required?
displayType The field type String No
label The field label String Yes
channelExtensions A set of channel-specific extension properties. Map<ChannelType, JSONObject> No
marginTop The amount of vertical space between this field and the previous field in the same column. Allowable values are none, medium (the default), and large. String No
labelFontSize The font size used for the field label. Allowable values are small, medium (the default), and large. String No
labelFontWeight The font weight used for the field label. Allowable values are light, medium (the default), and bold. String No
displayInTable A boolean FreeMarker expression that allows you to conditionally include a field in table layout in a dataSet response item. String No (defaults to true)
displayInForm A boolean FreeMarker expression that allows you to conditionally include a field in an The editForm Response Item, or in the form layout in a dataSet response item String No (defaults to true)

ReadOnly Field

Represents a read only field. All read only fields inherit the Field properties and have the following additional properties:
Name Description Type Required?
value The field value string Yes
width The suggested percentage of the total available width that the field should occupy in a table layout. number No
alignment The alignment of the value within a table column. The default alignment is right. "left", "center" and "right" No
Note

In Release 23.06 of Oracle Digital Assistant, read only fields do not render within input forms, even if they are received in the message payload.
TextField
The TextField element inherits all of the ReadOnly field properties. The displayType for this element is "text". It has the following additional properties:
Name Description Type Required?
truncateAt The position at which lengthly text is truncated and an ellipsis are added to indicate the value has been truncated. An integer No
fontSize The font size used for the field value. Allowable values are small, medium (the default), and large. String No
fontWeight The font weight used for the field value. Allowable values are light, medium (the default), and bold. String No
LinkField
The LinkField element inherits all of the ReadOnly field properties. It has the following additional properties:
Name Description Type Required?
linkLabel The label used for the hyperlink String No
imageUrl The URL of the image that opens a link when clicked. String No
MediaField
The MediaField element inherits all of the ReadOnly field properties. It has the following additional properties:
Name Description Type Required?
mediaType The field media type ("video", "audio", "image") String Yes
ActionField
The ActionField element inherits all of the ReadOnly field properties. It has the following additional properties:
Name Description Type Required?
action The action that should be performed when the user clicks the action button. Action Yes

Form

Represents an array of fields along with a title.
Name Description Type Required?
title The title that's displayed above the form layout String No
fields A list of read only fields in the form List<ReadOnlyField> Yes
formRows A list of rows displayed in the form. List<FormRow>  
actions A list of actions List<Action> No
selectAction The action that's executed when the form has been selected. When users hover over the form, the action's label displays as a tool tip (when supported by the channel). Action No
channelExtensions The channel-specific extension properties associated with the message JSONObject No

FormRow

Name Description Type Required?
columns A list of columns displayed in the form row. List <Column> Yes
selectAction The actions that's executed when the form has been selected. When users hover over the form, the action's label, it displays as a tool tip (when supported by the channel). Action No
separator Setting this property to true inserts a separator line above the content in the form row. Boolean No
channelExtensions The channel-specific extension properties associated with the message JSONObject No

Column

Name Description Type Required?
fields A list of fields that display vertically within the column. These fields must be ReadOnlyField instances when the column is used in a FormRow within a Form. The fields can be both read-only and editable fields when the FormRow is used within an EditFormMessagePayload. List<Field> Yes
verticalAlignment The vertical alignment of the column with respect to the other columns in the same form row. String No
width Determines the width of the column within the form row. Allowable values are auto (the default) and stretch. When set to stretch, the column takes all the remaining width after any auto-width columns are rendered. If there are multiple columns set to stretch, they evenly divide the remaining width. String No
channelExtensions The channel-specific extension properties associated with the message JSONObject No

The editForm Response Item

This response item forms the EditFormMessagePayload that's relayed through a channel to the client.
Name Description Type Required?
type The response item type. editform Yes
title The form title String No
items A list of fields, both read only and editable. List<field> Yes
formColumns The number of columns used for the form layout. The default is one column. Integer No
actions A list of card-related actions. List<Action> No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

The textInput Field

A field for entering free text. You can set the minimum and maximum characters for this field and enforce formatting using regular expressions.

This snippet illustrates collecting user input by referencing the generated submittedFields variable (a map).
      - displayType: textInput
        multiLine: true
        defaultValue: "${(submittedFields.value.Description)!''}"
        minLength: 10
        name: Description
        label: Description
        placeholder: What is the expense justification?
        clientErrorMessage: "Description must be 10 characters minimum, 50 characters maximum."
        maxLength: 50
        required: true
      - displayType: textInput
        multiLine: true
        defaultValue: "${(submittedFields.value.Notes)!''}"
        minLength: 10
        name: Notes
        inputStyle: email
        label: Notes
        placeholder: Expense notes (optional)
        maxLength: 50
        required: false
This snippet illustrates collecting the user input by referencing a composite bag variable.
Note

The referenced composite bag item can be a STRING.
      - displayType: textInput
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Tip'])!''}"
        defaultValue: "${(expense.value.Tip.originalString)!''}"
        displayInForm: "${(((expense.value.TipIncluded.yesno)!'') == 'NO')?then(true, false)}"
        name: Tip
        label: Tip
        placeholder: Enter the tip
        clientErrorMessage: Tip is required
        required: true
Name Description Type Required?
displayType The field type. textInput (a String) Yes
name A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
label The field label String No
defaultValue The initial value. Per the FreeMarker expression in the template, the value is an string when the referenced bag item (represented by myText) has no value ("${(submittedFields.value.myText)!''}"). String No
validationRegularExpression A regular expression that specifies the format for the text input. String No
multiline Setting this property to true allows users to input multiple lines of text. Boolean No
minlength The minimum number of characters required to validate the field. Users receive an error message if they input too few characters. Integer No
maxLength The maximum number, or limit of the characters. Integer No
inputStyle The format that's enforced on the client. The formats are:
  • text
  • email
  • url
  • tel
  • password
The default format is text when this property has not been defined.
String No
placeholder A hint that describes how to use this field. This text displays when users have not yet entered any input. For example:
What is the expense justification? Enter between 10 and 50 characters.
String No
autoSubmit When set to true, the form is partially submitted when the user has entered a value for the field. In FormSubmissionMessagePayload, partialSubmitField is set to the name of the field where autoSubmit is set to true. We recommend that you configure autosubmission for conditionally dependent fields. For example, set this property when one field should be displayed or hidden based on the value of another field, or when the allowable values of one field depend on the value set in another field. By autosubmitting a field that other fields depend on, the form can be updated immediately with the relevant changes to the dependent fields. String No
required Whether form submission requires user input in this field boolean No
clientErrorMessage The message used by some clients (MS Teams, Apple Business Messaging ) when client-side validation fails. On Slack, this property is only used when the editable form is displayed within the conversation page. It does not display in a modal dialog. String No
serverErrorMessage An error message that's sent to the client when the server-side validation of a form field value fails. When server-side errors of this sort happen, we recommend that the current form message be replaced, rather than a new message added to the conversation by configuring the channelExtensions property to indicate the last form message should be replaced. String No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

The datePicker Field

A field with a drop down calender that allows users to select a day, month, and year. The component's maxDate and minDate properties validate the user input.
Note

The Slack channel does not support this minimum and maximum value validation.
This code snippet illustrates how to capture the user input using the generated submittedFields variable (a map).
 - displayType: datePicker
        defaultValue: "${(submittedFields.value.Date)!''}"
        name: Date
        maxDate: "${.now?iso_utc[0..9]}"
        label: Expense Date
        placeholder: Pick a date in the past
        clientErrorMessage: Expense date is required and must be in the past.
        required: true
This snippet illustrates how to capture user input by referencing a composite bag variable.
     - displayType: datePicker
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Date'])!''}"
        defaultValue: "${(expense.value.Date.date?number_to_date?iso_utc)!''}"
        name: Date
        maxDate: "${.now?iso_utc[0..9]}"
        label: Expense Date
        placeholder: Pick a date in the past
        clientErrorMessage: Expense date is required and must be in the past.
        required: true
Name Description Type Required?
displayType The field type datePicker (a String) Yes
id A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
label A descriptive label. String No
defaultValue The default value for the field, formatted as YYYY-MM-DD. The template defines this String as an Apache FreeMarker expression that returns an empty string when the referenced composite bag item (represented by myDate) has a null value.
"${(submittedFields1.value.myDate)!''}"
String No
minDate The first date in the range of allowable days. The Slack channel does not support this client-side validation. String No
maxDate The last date in the range of allowable days. The template defines this String as the current day ("${.now?iso_utc[0..9]}"). The Slack channel does not support this client-side validation. String No
placeholder A description of the expected input that displays when the user has not yet selected a date. String No
autoSubmit When set to true, the form is partially submitted when the user has entered a value for the field. In FormSubmissionMessagePayload, partialSubmitField is set to the name of the field where autoSubmit is set to true. We recommend that you configure autosubmission for conditionally dependent fields. For example, set this property when one field should be displayed or hidden based on the value of another field, or when the allowable values of one field depend on the value set in another field. By autosubmitting a field that other fields depend on, the form can be updated immediately with the relevant changes to the dependent fields. String No
required Whether form submission requires user input in this field boolean No
clientErrorMessage The message used by some clients (MS Teams, Apple Business Messaging ) when client-side validation fails. On Slack, this property is only used when the editable form is displayed within the conversation page. It does not display in a modal dialog. String No
serverErrorMessage An error message that's sent to the client when the server-side validation of a form field value fails. When server-side errors of this sort happen, we recommend that the current form message be replaced, rather than a new message added to the conversation by configuring the channelExtensions property to indicate the last form message should be replaced. String No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

The timePicker Field

Allows the user to enter a time value within a specified range. The component's maxTime and minTime properties validate the user input.
Note

The Slack channel does not support minimum and maximum value validation.
The time picker field reads and writes the value in 24-hour format. The display format in the client channel might use 12-hour format with an AM/PM indication, but it should always write back a 24-hour formatted time.
The following snippet illustrates how to capture the user input using the generated submittedFields variable (a map).
      - displayType: timePicker
        defaultValue: "${(submittedFields.value.Time.value?time.xs?string['hh:mm a'])!''}"
        maxTime: "23:00"
        minTime: "13:00"
        name: Time
        label: Expense Time
        placeholder: What time was the expense?
        clientErrorMessage: This time is outside the limits.
        required: true
Name Description Type Required?
displayType The field type timePicker (a String) Yes
id A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
label A label that describes the time selection parameters. String Yes
defaultValue The initial value for this field, in 24-hour format. The template defines this String as an Apache FreeMarker expression that returns an empty string when the referenced composite bag item (represented by myTime) has a null value.
"${(submittedFields.value.myTime)!''}"
String No
minTime Defines the earliest allowable time, entered as HH:MM in 24-hour format. For example, 00:00 String No
maxTime Defines the latest allowable time, entered as HH:MM, in 24-hour format. For example, 13:00. String No
placeholder A hint for the input. Per the template, the example placeholder is Pick a time in the morning,which reflects the template's example minTime and maxTime values of 00:00 and 12:00. String No
autoSubmit When set to true, the form is partially submitted when the user has entered a value for the field. In FormSubmissionMessagePayload, partialSubmitField is set to the name of the field where autoSubmit is set to true. We recommend that you configure autosubmission for conditionally dependent fields. For example, set this property when one field should be displayed or hidden based on the value of another field, or when the allowable values of one field depend on the value set in another field. By autosubmitting a field that other fields depend on, the form can be updated immediately with the relevant changes to the dependent fields. String No
required Whether form submission requires user input in this field boolean No
clientErrorMessage The message used by some clients (MS Teams, Apple Business Messaging ) when client-side validation fails. For example, Time must be in the morning. On Slack, this property is only used when the editable form is displayed within the conversation page. It does not display in a modal dialog. String No
serverErrorMessage An error message that's sent to the client when the server-side validation of a form field value fails. When server-side errors of this sort happen, we recommend that the current form message be replaced, rather than a new message added to the conversation by configuring the channelExtensions property to indicate the last form message should be replaced. String No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

The numberInput Field

Collects number input within a specified range.
      - displayType: numberInput
        minValue: 5
        serverErrorMessage: "${(amountError.value)!''}"
        maxValue: 500
        defaultValue: "${(submittedFields.value.Amount)!''}"
        name: Amount
        label: Amount
        placeholder: Enter the expense amount (do not include currency symbol)
        clientErrorMessage: Amount is required and must be between 5 and 500 characters
Name Description Type Required?
displayType The field type numberInput (a String) Yes
name A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
label A descriptive label for the date value required from the user. String No
defaultValue The initial value. The template defines this String as an Apache FreeMarker expression that returns an empty string when the referenced composite bag item (represented by myNumber) has a null value. "${(submittedFields.value.myNumber)!''}" String No
maxvalue The largest allowable number. The Slack channel does not support minimum or maximum value validation. Integer No
minvalue A smallest allowable number Integer No
placeholder A hint that describes how to use the field. This text displays when the user has not yet entered a number. String No
autoSubmit When set to true, the form is partially submitted when the user has entered a value for the field. In FormSubmissionMessagePayload, partialSubmitField is set to the name of the field where autoSubmit is set to true. We recommend that you configure autosubmission for conditionally dependent fields. For example, set this property when one field should be displayed or hidden based on the value of another field, or when the allowable values of one field depend on the value set in another field. By autosubmitting a field that other fields depend on, the form can be updated immediately with the relevant changes to the dependent fields. String No
required Whether form submission requires user input in this field boolean No
clientErrorMessage The message used by some clients (MS Teams, Apple Business Messaging ) when client-side validation fails. On Slack, this property is only used when the editable form is displayed within the conversation page. It does not display in a modal dialog. String No
serverErrorMessage An error message that's sent to the client when the server-side validation of a form field value fails. When server-side errors of this sort happen, we recommend that the current form message be replaced, rather than a new message added to the conversation by configuring the channelExtensions property to indicate the last form message should be replaced. String No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

The singleSelect Field

Enables users to select a single value from a predefined list. You can style this control as a list that users can query and select from, or as a set of radio buttons. This element has channel-specific rendering:
  • On the Microsoft Teams channel, this element always renders as a list (even when layoutStyle is set to radioGroup) because Adaptive Cards do not support radio buttons.
  • On the Slack channel, this element renders as a list instead of a radio group when there are more than ten options.
The following snippet illustrates populating the list using the generated submittedFields variable (a map variable)
 - displayType: singleSelect
        defaultValue: "${(submittedFields.value.Type)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Expense Type
        placeholder: Select expense type
        clientErrorMessage: Expense type is required
        required: true

Tip:

Although clientErrorMessage is an optional attribute, we recommend that you define it for skills running on the Microsoft Teams channel because Adaptive Cards do not generate a message when the client-side validation fails.
This snippet illustrates how to populate the list by referencing a composite bag entity:
     - autoSubmit: true
        displayType: singleSelect
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Type'])!''}"
        defaultValue: "${(expense.value.Type.value)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Expense Type
        placeholder: Select expense type
        clientErrorMessage: Expense type is required
        required: true
Name Description Type Required?
displayType The field type singleSelect (a String) Yes
name A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
label The field label text that describes the contents of the single-select list. String Yes
defaultValue The default selection. The template defines this String value as an Apache FreeMarker expression that returns an empty string when the referenced composite bag item (represented by mySingleSelect) has a null value. "${(submittedFields.value.mySingleSelect)!''}" String No
options An array of the available options. The template defines these options statically with individual label and value pairs with String values, but you can populate the selection options dynamically using the iteratorVariable and iteratorExpression properties:
        defaultValue: "${(submittedFields.value.Type)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
In this snippet, the expense type values returned by the type and enum properties are sequenced in the list using the split built-in.
List<option> Yes
layoutStyle How the single-select options are laid out in the form. They can be grouped as a list (layoutStyle: list) or as radio buttons (layoutStyle: radioGroup). String  
placeholder A hint that describes how to use the field. It displays when the user has not yet made the selection. For example:
label: 
        placeholder: Select an expense type. You can pick only one.
This placeholder displays for the list layout rendering only.
String No
autoSubmit When set to true, the form is partially submitted when the user has entered a value for the field. In FormSubmissionMessagePayload, partialSubmitField is set to the name of the field where autoSubmit is set to true. We recommend that you configure autosubmission for conditionally dependent fields. For example, set this property when one field should be displayed or hidden based on the value of another field, or when the allowable values of one field depend on the value set in another field. By autosubmitting a field that other fields depend on, the form can be updated immediately with the relevant changes to the dependent fields. String No
required Whether form submission requires user input in this field boolean No
clientErrorMessage The message used by some clients (MS Teams, Apple Business Messaging ) when client-side validation fails. On Slack, this property is only used when the editable form is displayed within the conversation page. It does not display in a modal dialog. String No
serverErrorMessage An error message that's sent to the client when the server-side validation of a form field value fails. When server-side errors of this sort happen, we recommend that the current form message be replaced, rather than a new message added to the conversation by configuring the channelExtensions property to indicate the last form message should be replaced. String No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

The multiSelect Field

Allows users to choose one or more values from a predefined list. You can style this as a pick list that users can query, or as a set of checkboxes. This element has channel-specific rendering:
  • On the Microsoft Teams channel, this element always renders as a list (even when layoutStyle is set to checkboxes) because Adaptive Cards do not support multiselect checkboxes.
  • On the Slack channel, this element renders as a list instead of a set of multiselect checkboxes when there are more than ten options.
This snippet illustrates how to populate the list by referencing the generated submittedFields variable (a map).
 - displayType: multiSelect
        defaultValue: "${(submittedFields.value.Attendees?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Attendees
        placeholder: Select one or more attendees

This snippet illustrates referencing a composite bag entity to populate the list.
     - displayType: multiSelect
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Attendees'])!''}"
        displayInForm: "${(((expense.value.Type.value)!'') == 'Meal')?then(true, false)}"
        defaultValue: "${(expense.value.Attendees?map(a -> a.value)?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Attendees
        placeholder: Select attendees
        clientErrorMessage: Attendees are required when expense type is a Meal
        required: true
Name Description Type Required?
displayType The field type multiselect (a String) Yes
name A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
label The field label that describes the contents for the multiSelect list. String Yes
defaultValue The default selection. The template defines this String as an Apache FreeMarker expression that returns an empty string when the referenced composite bag item (represented by myMultiSelect) has a null value.
"${(submittedFields.value.myMultiSelect?join(','))!''}"
List<String> No
options An array of the available options. The template defines these options statically with individual label and value pairs with String values, but you can populate the selection options dynamically using the iteratorVariable and iteratorExpression properties:
        defaultValue: "${(submittedFields.value.Attendees?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
List<option> Yes
placeholder A hint that describes how to use the field. It displays when the user has not made any selections.
label: Attendees
        placeholder: Select one or more attendees
This placeholder displays for the list layout only. It is not available for checkbox layouts.
String No
layoutStyle The layout for the multiSelect options. The options are list and checkboxes. String No
autoSubmit When set to true, the form is partially submitted when the user has entered a value for the field. In FormSubmissionMessagePayload, partialSubmitField is set to the name of the field where autoSubmit is set to true. We recommend that you configure autosubmission for conditionally dependent fields. For example, set this property when one field should be displayed or hidden based on the value of another field, or when the allowable values of one field depend on the value set in another field. By autosubmitting a field that other fields depend on, the form can be updated immediately with the relevant changes to the dependent fields. String No
required Whether form submission requires user input in this field boolean No
clientErrorMessage The message used by some clients (MS Teams, Apple Business Messaging ) when client-side validation fails. On Slack, this property is only used when the editable form is displayed within the conversation page. It does not display in a modal dialog. String No
serverErrorMessage An error message that's sent to the client when the server-side validation of a form field value fails. When server-side errors of this sort happen, we recommend that the current form message be replaced, rather than a new message added to the conversation by configuring the channelExtensions property to indicate the last form message should be replaced. String No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

The toggle field

Presents a switch for two options. On the Slack channel, this control renders as check boxes.
Note

On the Slack channel, this element renders as a pair of radio buttons.
This snippet illustrates capturing the user input by referencing the generated submittedForms variable (a map).
      - displayType: toggle
        defaultValue: "false"
        name: TipIncluded
        labelOn: Tip
        label: Tip Included?
        valueOff: "false"
        labelOff: No Tip
        valueOn: "true"
This snippet illustrates capturing user input by referencing a composite bag variable.
      - autoSubmit: true
        displayType: toggle
        defaultValue: "${(expense.value.TipIncluded.yesno)!'YES'}"
        name: TipIncluded
        labelOn: "Yes"
        label: Tip Included?
        valueOff: "NO"
        labelOff: "No"
        required: false
        valueOn: "YES"
Name Description Type Required?
displayType The field type toggle (a String) Yes
id A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
label A label that describes what happens when the toggle is switched on. String Yes
defaultValue The initial value. If you want the toggle to be initially on, set this to the value of valueOn. The template defines this String as an Apache FreeMarker expression that switches on the toggle when the referenced composite bag item (represented by myToggle) has a null value.
"${(submittedFields.value.myToggle)!'true'}"
String Yes
valueOff The value when the toggle is switched off. The default value, per the template, is false (valueOff: "false" ). String Yes
valueOn The value when the toggle is switched on. The default value in the template is true (value On: "true" ) String Yes
labelOn A label for the toggle's on position String No
labelOff A label for the toggle's off position. String No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

Text Field

A field element contains the following properties:
Name Description Type Required?
displayType The element type. text (a String) Yes
name A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
value The raw value for the field String Yes
width The percentage of the total available width that the item should occupy in a table layout. The remaining width, starting from 100 minus the items with a width specified, is equally divided over the items without a width specified. Integer No
alignment The alignment of the value with a table column. left, center and right. The default is right. No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

Link

A field element contains the following properties:
Name Description Type Required?
displayType The field type link (a String) Yes
name A unique name for the field within the input form. This name is used as an identifier at runtime. String Yes
value The raw value for the field String Yes
width The percentage of the total available width that the item should occupy in a table layout. The remaining width, starting from 100 minus the items with a width specified, is equally divided over the items without a width specified. Integer No
alignment The alignment of the value with a table column. Allowable values are left, center and right. The default is right. String No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No

EditFormMessagePayload

This payload defines the editable form that is sent to the channels.
Name Description Type Required?
type The message payload type. editForm (a String) Yes
headerText The header text that's displayed above the form. String No
footerText The text that displays below the form and the actions, but above the global actions. String No
title The form title String No
formRows A list of rows displayed in the form. List<FormRow> No
fields A list of fields, both read only and editable. List<field> Yes
formColumns The number of columns used for the form layout. The default is one column. Integer No
actions A list of actions. List<Action> No
globalActions A list of global actions. The rendering of these actions is channel-specific. For example, actions on Facebook are rendered by reply_actions. List<Action> No
channelExtensions A set of channel-specific extension properties. For example, you may want to set the maximum height for Facebook Messenger. Map<ChannelType, JSONObject> No
Auto-Submitting a Field
When a field has the autoSubmit property set to true, the client sends a FormSubmissionMessagePayload with the submittedField map containing either the valid field values that have been entered so far, or just the value of the autosubmitted field (the implementation is channel-specific). Any fields that are not set yet (regardless of whether they are required), or fields that violate a client-side validation are not included in the submittedField map. If the auto-submitted field itself contains a value that's not valid, then the FormSubmissionMessagePayload is not sent, and the client error message displays instead.
Note

Microsoft Teams does not support autosubmission.

SubmitFormAction

Name Description Type Required?
type The action type submitForm (a String) Yes
postback The postback payload, which can include an action property for triggering navigation. We recommend that value for this property be taken from the FormSubmissionMessagePayload postback object. JSONObject No
variable The name of the variable that stores the submitted values. These values are in FormSubmissionMessagePayload. String No
processingMethod The processing instructions used by the Resolve Entities component for the submitted field values. You can set this to FormSubmissionMessagePayload, but you can also set:
  • mapVariable
  • separateVariables
  • compositeBag
.
String Yes
label The label for the display action. String Yes – You must specify at least one label value or imageUrl value.
imageUrl The image for the display action. String You must specify at least one label or imageUrl value.
channelExtensions A set of channel-specific extension properties. For example, you may want to set the max height for Facebook Messenger. Map<ChannelType, JSONObject> No
FormSubmissionMessagePayload
This payload is back by the channels to the ODA pipeline when the user has submitted a form by clicking a SubmitFormAction button. It has the following properties:
Name Description Type Required?
type The type of the payload. "formSubmission" (a String value) Yes
submittedFields Key-value pairs of the submitted field values. The key is the name (ID) of the field. Map<String, Object> Yes
postback The postback payload, which might include an action property to trigger navigation. We recommend that the value be taken from the SubmitFormAction JSONObject No
partialSubmitField The name of the field that triggers a partial form submission. Fields with the autosubmission enabled (autoSubmit: true) can trigger a partial form submission. String No

Updating the Input Form

When the end user submits the form, either because a field has autosubmit set to true, or because the user tapped the submitForm action button, there might be situations in which the user did not provide all the required information, or some field values contain an invalid value. In such a case, the dialog engine will send a new EditFormMessagePayload, but that message should replace the previous form message. To instruct the client channel to replace the previous form message, instead of adding a new form message to the conversation, configure the channel extension property replaceMessage as follows:
- channel: ${system.channelType}
  properties:
    replaceMessage: "${system.message.messagePayload.type == 'formSubmission'}"
At runtime, this property is added to the root-level channelExtensions element of the common response component payload:
...,
"channelExtensions": { "replaceMessage": "true"}

The dataSet Response Item

The dataSet response item enables you to create tables and forms. It includes the following properties.

Property Description Required?
layout The layout style used to render the dataSet. Allowable values are table, form and tableForm. Yes
formColumns The number of columns used to render items in a form layout. Only applicable when the layout is form or tableForm. Default to 1. No
showFormButtonLabel The label used to open the form dialog in a tableForm layout style. This is currently only used on Slack channels. The other channels support expanding the table row to show the additional items in a form layout No
data Used to define a data entry in the dataSet. See DataSet data Properties Yes

DataSet data Properties

The data property of the dataSet response item includes the following sub-properties.

Property Description Required?
iteratorExpression Defines a Freemarker expression that returns a list of entries to iterate over, allowing you to dynamically add multiple data entries to the dataSet. No
iteratorVariable Specifies the name of the iterator variable that you can use to reference the current data entry within the list of data entries that are iterated over. No
rangeSize The number of data entries that will be displayed at once when you have specified the iteratorExpression and iteratorVariable properties. No
visible Determines how messages display per user input and channel. See The visible Property. No
formTitle The title used for the form dialog in tableForm layout in the Slack channel. Defaults to View details. No
items The data items that should be displayed for each data entry. See DataSet Data Item Properties. Yes

DataSet Data Item Properties

Property Description Required?
width The percentage (expressed as an integer) of total available width the item should use in a table layout. The remaining width, starting from 100 minus the items with a width specified, is equally divided over the items without a width specified. No
alignment The alignment of the value with a table column. Allowable values are left, center, and right. Defaults to left. No
displayType The display type of the item. Allowable values are text and link. Defaults to text. No
linkLabel The label used for the hyperlink when the display type is set to link. Defaults to the value of the item's value property. No
displayInTable Defines whether the item should be displayed as a column in the table. This property is only applicable in tableForm layout. Defaults to false. No
displayInForm Defines whether the item should be displayed as a field in the form. This property is only applicable in tableForm layout. Defaults to false. No
label The label of the data item. Yes
value The value of the data item. Yes

The system.entityToResolve Variable

The system.entityToResolve variable provides information on the current status of the entity resolution process as performed by Resolve Entities and Common Response components. You will typically reference the properties of this variable value in the Common Response component metadata when you want to customize messages. You can use it to define the logic for an entity's error message, or for various properties that belong to the Resolve Entities and Common Response components. Append the following properties to return the current entity value:
  • userInput
  • prompt
  • promptCount
  • updatedEntities
  • outOfOrderMatches
  • disambiguationValues
  • enumValues
  • needShowMoreButton
  • rangeStartVar
  • nextRangeStart
You can also reference the properties in FreeMarker expressions used bag item properties like prompt, errorMessage and validation rules.
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

Common Response 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.

Description of message_validation.png follows

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 referenced 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.
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