article by Frank Nimphius, October 2019
Using multi-select lists are common user interface widgets in mobile and web application development. In conversations, graphical multi-select lists are difficult to create because users not only would need to select values, they also would need to click on a button to progress to a next dialog flow state. Here, form based use cases as in web and mobile are much better suited for the use of multi select lists.
Still, multi value selects is an options available in Oracle Digital Assistant. As shown in the image below, at runtime, the list value options are displayed for the user to type one or many list value options separated by a space character. Notice that though item 6. is "garlic oil", the selection also works by simply typing oil. The reason for this to work is that the multi select list is implemented on a custom value list entity, which makes smart entity extraction using synonyms an option. You could also select values by typing: I want cheese and garlic and cream. The entity only selects values it knows about as entity values of synonyms.
This article explains how to create multi select lists in Oracle Digital Assistant skills.
Notice in the image above, how the selected extras, cheese, garlic and olive oil got printed using a System.Out built-in component.
Entity Definition
Multi-select values lists are defined on a custom value list entity. The image below shows a custom entity named "Extras".
The entity type is set to Value list and the values and synonyms are defined as shown in the image below. Notice the synonym "oil" for olive oil. This allows users to use a shorter term than the original value.
Also on the entity definition, you find a toggle Multiple Value, which is shown in the image below. By enabling this toggle, the entity now does allow multiple values to be added at runtime. The values, when read, e.g. for printing, are then returned as an array. For printing you could use e.g. ${extras.value?split(',')} to obtain a comma separated list of values.
System.CommonResponse Component
Before you can display the multi value content of an entity, you need to understand how to build the user input so data can be saved in the entity. Basically there are two built-in components you can use for this in Oracle Digital Assistant: System.ResolveEntities and System.CommonResponse component. In this example, I will explain the use of the System.CommonResponse component purely because it gives you more options than the System.ResolveEntities component, which is more of a "black-box".
First, you start with defining a context variable of the entity type. So the "extras" variable in this example references the entity name "Extras".
The System.CommonResponse component references the extras variable in its "variable" property. This ensures two things: Values typed by the user are saved in the extras variable, and the dialog flow state is skipped when the extras variable already contains values. The latter could be through NLP, for which the nlpResultVariable property is set to "iResult" (which is the nlpresult type variable also defined for the dialog flow . though not shown on the image above)
Note: The "text" property defines the prompts displayed to the user. Though not in the scope for this article, the prompt can be read from the entity too, which is why instead of the prompt text, the text property contains an Apache FreeMarker expression. Using prompts defined on the entity allows you to have random prompts as well, so your bot appears less robotic when a users is prompted again for providing extras.
The only setting required to make multi-value selects in Oracle Digital Assistant working is to reference a variable of a custom entity type that has the Multiple Value toggle switched on. As simple as that.
Handling User Selections
As mentioned, users type multiple value from the list separated by a space character. In the example, chances are that users don't want extras. For this the entity contains the value 'no extra', which in the print out then is looked for so the order confirmation message can be adjusted. The below expression checks whether the entity value contains 'no extra' as a value. And if it does, it prints 'NONE', whereas otherwise it prints a list of selected extras. Instead of printing the user selected values (as in this example) you could also pass them as input arguments to a custom component.
You chose "${selectedExtras.value?lower_case?contains('no extra')?then( 'NONE',selectedExtras.value)}" for your extras
The image below shows the order confirmation the extras are printed with. Again, notice the display of cheese, garlic and olive oil.
The image below shows the part of the dialog flow state that prints the message from the extras variable. Notice that ${extras.value} prints the selected values as an array. To build a comma delimited string, you use Apache FreeMarker: ${extras.value?split(',')}
Note: for reasons of a better image display, I put a line break in the BotML after the "('no extra')?" string. Note that this would not work at runtime. So the whole string must be put as a single line as shown here: You chose "${selectedExtras.value?lower_case?contains('no extra')?then( 'NONE',selectedExtras.value)}" for your extras
Could you use the index numbers to select values?
Could you use the index numbers in front of the list values for the user to select the values? Yes, you can. However, for this to work, you need to reference the custom entity as a bag item in a composite bag entity.
The multi-value list that is directly created from an entity does not support the use of the index numbers as of the time of writing. To use the index numbers, you create an entity of type Composite bag and add a bag item that you then select the "Extras" entity as the item type. All settings of the Extras entity will be automatically imported.
To learn more about composite bag entities, check the following tutorial
https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorial-entities/index.html
Related Content:
TechExchange: How-to Use the System.ResolveEntities Component in Oracle Digital Assistant
TechExchange Quick-Tip: Sorting Entity Derived Lists
TechExchange Quick-Tip: How-to assign keyword shortcuts to static and dynamic lists created with the System.CommonResponse component in Oracle Digital Assistant TechExchange: All 2-Minutes Oracle
Digital Assistant Tech Tip Videos on YouTube
