article by Frank Nimphius, May 2021
Most messengers used with chatbots do not support multi-select lists as a widget for building user interfaces. In a previous Oracle TechExchange article, I discussed how, using Oracle Digital Assistant, you can still implement multi-select lists for data stored in value list entities (https://blogs.oracle.com/mobile/techexchange-quicktip%3a-creating-multi-select-lists-in-oracle-digital-assistant). In this article, I will explain how you can do the same for values that are not entity based but queried from a backend service.
How a multi-select value list looks in Oracle Digital Assistant
The screenshot below shows the example I created and demonstrated in the previous article. The list of values was created from a list of values entity that has been configured to accept multiple values entered by a user. At runtime, users could then use the index numbers, or the labels, in front of the choices to select one or many items (see how the selection of cheese, garlic and oil are reflected in the order confirmation).
The Non-Entity Based Solution
The non-entity based solution (in fact it uses an array of values defined in the dialog flow) looks very similar to the solution I built in the previous article. The main difference is that users can only select list elements by their index numbers and not their labels.
The sample that you can download at the end of this article displays a list of names (names of people who all work in Oracle Digital Assistant product management). The user can now select one or many users by typing the index number(s) separated by a blank character. So in the sample below, users 1 and 3 where selected, which then – for the sample -lead to those user names to be printed. In a real bot implementation you then would do something with the selected users (e.g. send them an invitation for a meeting)
What also works for the sample is if the index numbers of the users are contained in a conversational user message, which indicates that still an entity is involved.
Implementation
To allow users to select multiple value list entries, a NUMBER entity is used. The NUMBER entity is a built-in (system) entity that extracts numbers (as written on the tin). The problem with built-in properties are that you cannot customize them e.g. to configure the NUMBER entity to accept multiple user values. To make this work nevertheless, you wrap them in a composite bag entity as shown in the image below.
The cbe.selectedUserIndexes composite bag entity has a single bag item (selectedUsers) of type NUMBER entity. The selectedUsers bag items is configured as shown in the images below. The first mage sows the bag item setting to accept multiple value entries, as well as an error message that uses a resource bundle key reference and that gets displayed when a user fails to provide a valid numeric entry.
The second image shows the configuration for prompts, which are displayed in a random order to the user
To display the list of values, the composite bag entity needs to be referenced from a dialog flow variable. In addition, a variable needs to be defined that holds an array of values to be shown in the list
The values to be displayed in the list (person names in my sample) are queried through a custom component that saves them in a variable in the dialog flow
With this, the multi-select list is created using a System.CommonResponse component. The BotML of the list definition is shown in the image below
Notice 3 things in the image above:
- The variable property points to the composite bag entity type variable name. This way, all user input get saved in the composite bag entity bag item (which is of type NUMBER entity)
- The list of values is created from an array variable referenced in the iteratorVariable property
- The values in the array are printed as text labels within a single message bubble. Using Apache FreeMarker, the index numbers are added in front of each array element (see text: property)
At runtime, when the user types the index numbers of the value list items she wants to select, the numbers are getting stored in the composite bag entity bag item. The bag item contains an array of NUMBER entity objects.
To get the selected users, the index numbers needs to be exchanged for the user names. This is where a second custom component is needed
The custom component requires 3 input parameters:
- The name of the variable that holds the array of users queried by the first custom component. This is important to ensure that the selected users are read from the same set of users that were displayed in the list-of-values
- The name of the composite bag entity variable is needed for the custom component to look up the bag item for the array of NUMBER entity object.
- The variable property points to the dialog flow variable of type "string" or "map" that should receive the array with the selected users
Last but not least, the variable with the selected user names is printed (as in my example) or further processed (in a real – life bot)
What if a user types an invalid value item index
Some users are naughty by nature! Someone certainly will try to send an index for which no user choice exists.
As shown in the image below, the implementation you can download for this article simply ignores those values.
The custom component that handles the user selection can easily be changed to throw an error instead. Or, an entity event handler could be created for the composite entity to validate the user input and, if the input contains index numbers that are larger than the array of values, thrown a validation error.
Downloads
Skill to import (requires ODA 21.04 or later)
Related Content
TechExchange-QuickTip: Creating Multi-Select Lists in Oracle Digital Assistant
TechExchange Quick-Tip: Accessing The Current Range Start For Bag Items In A Composite Bag Entity
TechExchange Quick-Tip: Access And Read Objects In An Array By Their Index Position In The Array
TechExchange Quick-Tip: Setting Composite Bag Entity Item Values From A Custom Component
Related Videos
Oracle Digital Assistant Design Camp: Custom Component Service Design & Development
Oracle Digital Assistant Design Camp: Learn to love the System.CommonResponse component
Oracle Digital Assistant Design Camp: Understanding Entity Event Handlers
