article by Frank Nimphius, March 2019
The conversation interface is not just about text messaging. Most messengers support a list of values, and many even support card layouts. Chatbot users select a value from a list by either tapping the list item or typing the displayed list item label into the message field. In this article I explain how to assign keywords as shortcuts to list items (and card layouts, as it is the same code) for users to select an item. With card layouts, when not all cards are displayed in a horizontal carousel (so when some are hidden), then, using predictable keywords, keyword shortcuts allow users to select an item even if it is not visible*
* the restriction is when you use page ranging, in which case a card is not hidden but not available at all. In this case you can only access those cards that belong to the current displayed range of cards.
Keywords in static lists
The Oracle Digital Assistant dialog flow state definition shown in the image below defines a static list of values for airports. The airports itself are defined in a value-list entity that is referenced by the "airport" variable. The OBotML (markup language used in the dialog flow builder) code in the image below shows the list defined using the System.CommonResponse component. Each selectable item in the list is defined by an action (postback), which defines the label to display on the item, as well as the variables and values that are getting updated when the user taps on a list item.
The image below shows the runtime view of the OBotML code above. As you can see, a list of airport cities is displayed to the user, which makes sense given that users have a better understanding for the names of the city an airport is located in than the actual airport code. If you try selecting an airport by typing the first letter of the city name (L)ondon, (A)msterdam, (P)aris etc. then the selection fails entity validation as it is not a valid city or airport code. Similar, providing the position of an item in the list (e.g. "second") does not work.
So, how can you make this work? The solution is, as shown in the image below, to use the keyword property on the action items in the System.CommonResponse component configuration. The OBotML code below configures the following shortcuts for each select item:
- First letter of the label. This can be typed by the user as uppercase or lower case to select the item
- The number of the select item's position in the list. E.g. 2 to select "London"
- The text version of the index of a select item in the list: "second", "third" etc.
Keywords don't need to match allowed entity values. There also is no requirement to set multiple keywords. It is perfectly fine to set only one, or, as the default is, none. Whatever keyword you think provides a benefit to users is a good one to set.
The image below shows the use of the shortcuts at runtime. Note that the above OBotML code also annotated the select item label with an indication that the first letter of the label can be used as a shortcut (somehow you need to let users know that keyword shortcuts exist). As you can see from the image below, short cuts can now be used to select an item in the list-of-values.
Keywords in dynamic lists
Dynamic lists are those that read their values from a list of values saved in a value-list type entity or an array. Here too you can use keywords, though the definition of the keywords need to be dynamic too. The code sample in the image below reads its list items from the entity. The airport variable referenced from the System.CommonResponse component is of an entity type, which means that the list of airports stored in the entity can be read using <variable name>.type.enumValues.
The iteratorVariable property in the System.CommonResponse component uses airport.type.enumValues to generate (stamp) an action item for each value in the "Airports" entity. When the list is created dynamically at runtime, then the current "stamped" action values are accessible from ${enumValue}.
The OBotML code below creates the following keyword shortcuts using Apache FreeMarker expressions
- First letter of the label
- numeric position of item in list (lists are zero based, which is why the expression uses '+1')
- the string representation of the index (this uses a switch statement, which may not be usable for very long lists)*
* there is a typo in the code shown below. It should be "fifth", not "fith". Anyway, hope you get the idea 😉
The image below shows the runtime view for all three options (first letter, number, index as string). Note the select item labels that indicate the first letter to be a shortcut. Again, as the label needed to be generated at runtime, it uses Apache FreeMarker for it.*
*If you have two or more labels starting with the same initial letter, then this won't work for shortcuts. In this case I suggest you use the first two or three letters (whatever makes them unique)
Benefit of dynamic shortcuts
The benefit of dynamically generated shortcuts is that, e.g. in the case of multi-language bots, a change in the item label still allows to create valid shortcuts. Even if the label string is read from a resource bundle, Apache FreeMarker works for extracting the initial letter.
Related Articles
TechExchange: How-to Populate a Common Response Component Iterator from a Custom Component
TechExchange Quick-Tip: Dynamically and Conditionally Reduce the Number of Items Displayed in a List
