An introduction to the new composite bag entities in Oracle Digital Assistant

By Frank Nimphius

March/April 2019

Oracle Digital Assistant is the next generation of the Oracle chatbot platform. It manages and coordinates multiple smaller-scope skill bots in a composite chatbot solution that helps users complete multitask conversations.

Dialog flows in Oracle Digital Assistant skill bots define the user/bot conversations needed for completing a specific business task. A dialog flow is like a script whose goal is to understand what a chatbot user wants and collect the information needed to perform a particular task. Like human agents in customer service, chatbots can skip portions of a scripted conversation if the information to be collected has previously been provided by the user.

Before Oracle Digital Assistant, chatbots built with the Oracle Cloud platform required a dialog flow state to be defined for each information entity. For example, to create a chatbot for ordering pizza, you needed to create separate dialog flow states to ask for the pizza type, to ask for the pizza size, to ask for the type of crust, and to ask for additional toppings.

With Oracle Digital Assistant, you are no longer required to write all of these separate dialog flow states. Instead, using the new composite bag entity feature, you can group related information into a composite data object. The composite data objects are then automagically resolved at runtime.

This article provides an overview of composite bag entities. Following the hands-on instructions, you will build a composite bag entity for a pizza ordering bot that you then use to reduce the number of dialog flow states in the provided sample bot.

About Composite Bag Entities

In general, you use entities to extract important information from user messages through natural-language processing (NLP). Entities in Oracle Digital Assistant can be of various types, including value list, entity list, regular expression, entities derived from other entities, and composite bag.

Entities are associated with context variables in the bot dialog flow. If the value of an entity gets extracted from the user message through NLP, then the UI component that references the context variable associated with the entity is not rendered, meaning that users will not be prompted for information they have already provided.

Composite bag entities in Oracle Digital Assistant enable you to define entities and variables of type string, location, and attachment as attributes—bag items—of a single object. When a composite bag entity is resolved at runtime, a prompt gets generated for each entity type attribute that did not get its value from the user message through entity extraction in NLP.

In this article’s pizza ordering bot sample, the composite bag entity describes the pizza the user attempts to order. The pizza composite bag entity object contains attributes referencing the PizzaType, PizzaSize, PizzaCrust, and CheeseType entities. In addition, a pizza object may have a customer name attribute associated with it, so the waiter can identify the customer.

At runtime, composite bag entities are referenced through a context variable that has the custom composite bag entity defined as its type. To resolve a context variable of a composite bag entity type in a dialog flow, you create a dialog flow state that uses the System.ResolveEntities or the System.CommonResponse component for rendering the bot response. Both components are able to render user prompts as input text and lists.

The difference between the two system components, when used with composite bag entities, is that the System.CommonResponse component enables you to customize the rendered bot UI.

Composite bag entities, however, can do more than just group entities and variables into a single object. For each item in a composite bag entity, you can define validation rules, prompts, support for multiple values, fuzzy matching, and other features. For entity references to value list entities, you can specify or inherit a range size value that determines when pagination controls should automatically be displayed.

Both the System.ResolveEntities and the System.CommonResponse components enable you to visit other dialog flow states.

Getting Ready

In Oracle Digital Assistant, child bots are referred to as skills, or skill bots. In the hands-on instructions for this article, you are working with a skill bot only. Skill bots in Oracle Digital Assistant can be tested standalone with the embedded tester.

A starter skill bot is provided, so you can focus on building and implementing the composite bag entity, following the instructions in this article.

These are the prerequisites for following along with the hands-on steps in this article:

• You need a trial or paid instance of Oracle Digital Assistant. You can sign up for a free trial at cloud.oracle.com.
• You need to download and extract the resources for this hands-on exercise to your computer.

Follow these initial hands-on steps to start the service and import, train, and test the bot.

1. Start Oracle Digital Assistant in a browser, by typing https://<your cloud URL>/botsui/ into the URL field.
2. Click the hamburger icon () at the upper left.
3. Choose Development and then Skills.
4. Close the menu, by clicking the hamburger icon ().
5. Click the Import Skill button at the upper right.
6. Navigate to the downloaded and extracted resources for this article and then to the starter folder.
7. Select the OracleMagazinePizza(1.0).zip starter bot file, and click Open.
8. Click the OracleMagazinePizza tile in the Bot dashboard to open the bot.

Note: If you don’t see the imported bot because other bots fill your screen, type OracleMagazine into the Filter field above the + New Bot tile.

9. Train the bot, by clicking the link in the upper right.
10. In the opened dialog box, accept the default settings and click Submit.
11. Run the embedded bot tester, by clicking the test icon () in the left menu.

Note: In Oracle Digital Assistant, the tester opens in full window view. To switch back to the bot, click the Close button.

12. Type I like to order a pizza into the Message field, and press the Enter key.
13. Select values from the menus for pizza crust type and pizza size.
14. When asked for the pizza type, type supreme and press the Enter key.
15. Click the Reset link at the top of the tester window.
16. Click the Close button in the top right of the tester window.

What you just did: You just explored the functionality of the simple pizza order skill. Note that for this article and its hands-on instructions, the order in which the bot responses are displayed and how they are getting displayed are relatively unimportant. In a real bot implementation, user experience matters and the UI should be more pleasing to the eye. For this article, it is important for you to understand how this little bot conversation is built, which is what you will do next.

Understanding the Dialog Flow

All bot conversations are defined as dialog flows in the dialog flow builder. Take a look at some dialog flow content to see how it is used in a bot conversation.

17. Open the dialog flow builder, by clicking the dialog flow builder icon () in the left menu.
18. In the dialog flow builder, explore lines 16 to 52, which define the conversation you just tested.
19. Note that each step in the conversation is defined as a state in the dialog flow builder (lines 15, 25, 35, and 45).

Note: All of these conversation states are required to collect the information necessary for ordering a pizza. The variables that are populated within the states are of an entity type and are defined in lines 9–11.

Line 12 defines the iResult variable, which is of type nlpresult. This variable is used to extract information from the user message.

20. Again, run the embedded bot tester by clicking the test icon () in the left menu.
21. Type I like to order a thick pizza salami into the Message field, and press the Enter key.
22. In the displayed menu, select a size for the pizza.
23. Note that the pizza order was completed within a single bot/user interaction.
24. Click the Reset link at the top of the tester window.
25. Click the Close button at the top right of the tester window.
26. Open the dialog flow builder, by clicking the dialog flow builder icon () in the left menu.
27. Note the use of the nlpResultVariable property in lines 31, 41, and 50. The component property checks whether the requested information is contained in the initial user message. If it is, the component will not render and navigation will continue to the next state.

Cleaning Up the Dialog Flow

Composite bag entities help reduce the overall number of dialog flow states needed for a task such as ordering pizza. To prepare to use a composite bag entity in the pizza order skill bot, you first need to clean up the current dialog flow.

28. In the dialog flow builder, select and delete lines 25–52. Ensure that the intent and done states are kept as they are.
29. Change the value of the OrderPizza transition action (line 21) to "getOrder". Figure 1 shows the intent state with this change.

Figure 1: OrderPizza action transition value changed to “getOrder”

What you just did: You prepared the dialog flow for adding a composite bag entity variable state. The OrderPizza transition action is followed when the NLP engine understands the user message as a pizza order. The value of this action needed to change, because you removed the getCrust state. You will create the getOrder state later in the hands-on instructions.

Building the PizzaOrder Composite Bag Entity

Composite bag entities are composed of existing entities as well as variables of type string, attachment, and location.

The starter skill bot comes with the following entities defined: CheeseType, PizzaCrust, PizzaSize, and PizzaType. Following the instructions in this section you are going to create a new composite bag entity with the name PizzaOrder.

30. Navigate to the entity editor, by selecting the entities icon () in the left menu.
31. Click the PizzaType entity. PizzaType is a value list entity that holds a set of pizza names and synonyms that are valid to order. (It’s not covered in these hands-on instructions, but a list of values can be dynamically populated from a remote service.)

Note: The only other property of interest for this article is the Prompts property. Here you can define one or more user prompts that get randomly displayed for an entity if the entity is resolved by the System.ResolveEntities or System.CommonResponse component. If an entity is referenced in a composite bag entity, then the defined prompts are used if they are not overridden in the composite bag entity.

32. Click the + Entity button.
33. Type PizzaOrder in the Name field.
34. In the Configuration section, from the Type menu, select Composite Bag.
35. Click the + Bag Item button.
36. Type PizzaType in the Name field.

Note: The Name field value doesn’t need to be set to the name of the entity it references. You can define any name you like for a bag item. The name of the bag item will be referenced in the dialog flow to read the value saved for an entity.

37. From the Type menu, select Entity.

Note: At this time, a dialog box appears with the following message: “Entity CheeseType has been set to the bag item PizzaType. Do you want to copy over its properties also here? Any edits previously made to this bag item will be lost. Are you sure you want to continue?” Ignore this message, and close the dialog box, by clicking the X icon in the header.

38. From the Entity Name menu, select PizzaType.
39. Click Overwrite in the opened confirmation dialog box.
40. Keep the default settings for all other properties, and click Close.
41. Repeat steps 35–40 with the following information to create the corresponding bag items:

    Name	Type	Entity name
    PizzaSize	Entity	PizzaSize
    PizzaCrust	Entity	PizzaCrust

42. Next associate the PizzaOrder entity with the OrderPizza intent. To do this, open the intent editor, by clicking the intents icon () in the left menu.
43. Select the OrderPizza intent.
44. Click the + Entity button at the top right.
45. In the New Entity list, enter PizzaOrder to search for the PizzaOrder entity, and select it.
46. Train the bot, by clicking the link at the top right.
47. After training the skill bot, click the icon (on the same line as the Description label) to test the composite bag entity extraction in the embedded intent tester.
48. In the intent tester, type I like to order a pizza salami into the Message field and click Send.
49. You should see the PizzaOrder entity getting resolved from the user message, as shown in Figure 2.

    

    Figure 2: Intent tester with PizzaOrder entity resolved from the user message

50. Click the X icon in the upper right to close the intent tester.

What you just did: In this part of the hands-on instructions, you created a composite bag entity to hold the pizza order information. The order in which entities are added as bag items to a composite bag entity is the default order in which the entities are resolved at runtime. (You can also change the order by changing the configuration.) Finally, you associated the entity with the OrderPizza intent and tested the entity extraction through NLP in the embedded tester.

Next, add the use of the composite bag entity to the dialog flow.

Referencing the Composite Bag Entity in the Dialog Flow

To use the PizzaOrder composite bag entity in the pizza order skill bot, you need to associate it first with a context variable. The variable is then referenced from a dialog flow state with the System.ReferenceEntities component. In the end, when testing the bot, the behavior is the same as in the starter skill bot, although with fewer lines of code to write.

51. Open the dialog flow builder, by clicking the dialog flow builder icon () in the left menu.
52. On line 13, create a new context variable with the name pizzaOrder of type "PizzaOrder":

    pizzaOrder: "PizzaOrder"
    

53. Click the + Components button.
54. In the opened dialog box, select the user interface () category.
55. Select the Resolve entities template (the third template option from the bottom of the list).
56. Switch the Remove Comments toggle to on.
57. From the Insert After list, select intent.
58. Click the Apply button.
59. Change the resolveEntities state name to getOrder.
60. Delete the following properties: maxPrompts, cancelPolicy, transitionAfterMatch, autoNumberPostbackActions, headerText, footerText, showMoreLabel, and translate.
61. Remove the following elements: actions, match, and cancel.
62. In a line under the transitions element, add

    next: "done"
    

Note: The next element must be indented two spaces, but the transitions element does not.

63. Edit the remaining System.ResolveEntities component properties as follows:

    Property	Value
    Variable	"pizzaOrder"
    nlpResultVariable	"iResult"

Note: The getOrder state should now look like it does in Figure 3.

Figure 3: getOrder state after the changes

64. Next, edit the done state: Change the value of the text property from

    "Your ${size.value} ${type.value} Pizza is on its way."
    

    to (in a single line)

    "Your ${pizzaOrder.value.PizzaSize}, ${pizzaOrder.value.PizzaCrust} 
    ${pizzaOrder.value.PizzaType} is on its way."
    

65. To ensure that your dialog flow is well formatted, click the Validate link in the upper right corner. If an error is found, correct the error and validate again.
66. If the dialog flow was validated successfully, run the embedded bot tester, by clicking the test icon () from the left menu.
67. Type I like to order a pizza into the Message field, and press the Enter key.
68. You should see a menu listing the pizza types. Select a pizza.
69. In the next menu, select the pizza size.
70. Finally, select a pizza crust type.
71. With the order confirmation displayed, click the Reset link at the top of the tester.
72. Next, type I like to order a thick pizza salami into the Message field to test NLP entity extraction, and press the Enter key. You provided information about the pizza type and the pizza crust in the input message, so the bot asks only for the pizza size.
73. Click the Reset link at the top of the tester window.
74. Click the Close button at the top right of the tester window.

What you just did: In this section, you created a new context variable for the PizzaOrder entity. When testing the bot conversation, you could see that the user is prompted to provide information that was not contained in the initial user message.

Adding the CheeseType Entity to the Composite Bag

Besides reducing the lines of code that need to be written for a user/bot conversation, composite bag entities make it really easy to add or remove information:

75. Open the entity editor, by clicking the entities icon () in the left menu.
76. Select the PizzaOrder entity.
77. Click the + Bag Item button.
78. Type Cheese in the Name field.
79. From the Type field menu, select Entity. The Entity Name field should automatically be set to CheeseType.
80. Click Overwrite in the opened dialog box.
81. Select the dialog flow builder icon ().
82. Change the value of the text property in the done state from

    "Your ${pizzaOrder.value.PizzaSize}, ${pizzaOrder.value.PizzaCrust} 
    ${pizzaOrder.value.PizzaType} is on its way.”
    

    to

    "Your ${pizzaOrder.value.PizzaSize}, ${pizzaOrder.value.PizzaCrust} 
    ${pizzaOrder.value.PizzaType} with ${pizzaOrder.value.Cheese} is on its way."
    

83. Click the Close button on the upper right.
84. Click the test icon () in the menu on the left.
85. Type I like to order a small thick pizza salami into the Message field, and press the Enter key.
86. Because you did not specify a cheese type, this information is now requested in the bot response.
87. Select a cheese type.
88. You should see the changed confirmation message with the type of cheese added.

What you just did: With minimal effort, you added information to the PizzaOrder composite bag entity. A change like this requires more work if the order process uses dialog flow states to collect the individual pieces of required information. This certainly is another argument for using composite bag entities.

Note: Before adding any entity as a bag item, you always set the name of the bag item to the name of the entity it references. The bag item name is what is getting referenced when composite bag entity values are being accessed. This is why ${pizzaOrder.value.Cheese} is used in the confirmation message instead of ${pizzaOrder.value.CheeseType}.

Conclusion

Composite bag entities in Oracle Digital Assistant enable you to group related information in a single object, an object that is comparable to a business domain object. Changes applied to composite bag entities have an immediate impact on the bot/user conversation.

In this article and its hands-on instructions, I introduced the concepts and basic use of composite bag entities. Advanced functionality such as value disambiguation, fuzzy matches, validation, error messages, and multiple entity values are also worth mentioning, although they fall outside the focus of this introductory article.

Next Steps

READ “Oracle Digital Assistant Version 18.4.3 Introduces Skill Chatbot Capability.”

TRY Oracle Digital Assistant.

DOWNLOAD the bot for this article.

Illustration by Wes Rowell