article by Frank Nimphius, October 2023

A composite bag entity can contain bag items of the same entity type. For example, the example skill that you can download at the end of this blog article has a bag item “TravelBooking” of type DATE_TIME, subtype Interval. The interval has two nested bag items of type Date: startDate and endDate. When a user sends a message whose value matches both bag items, a standard disambiguation dialog is displayed as shown in the image below for the user to select which bag item should receive the detected value.

As you can see in the image above, each candidate bag item is displayed as a select button. If the user selects a button, then Oracle Digital Assistant updates the associetd bag item with the disambiguationn value (June 12 2024 in the example above).

While the default prompt "Which item do you want to set to" can be customized in the resource bundles of the skill that hosts the composite beg entity, other customizations need to be applied using an entity event handler. Customization you can think of may include

• Adding an extra button to dismiss the dialog
• Displaying a prompt conditional to the type of disambiguation (e.g. a date disambiguation would be prompted different than a number disambiguation)
• Displaying the choices as a carousel of cards instead of a list of values
• Suppressing the disambiguation dialog and setting the disambiguation value based on custom logic (e.g. if the start date is not set, then always set the date to the start date as an end date does not make sense without a start date)

Hint: The labels displayed on the buttons in the image above are read from the bag item. Each bag item has a Label field that you can use tospecify a himan friendly label to be displayed. The Label field can also take an expression to read the string from a resource bundle.

Creating a Custom Disambiguation Dialog Using a Entity Event Handler

First, let's create a custom disambiguation dialog that does exactly what the standard disambiguation dialog does. Once you see this working, you'll get an idea of how to customize it.

You create a new event handler from the composite bag entity. Once created, you will see the event handler name and a pencil icon to open the browser-based JavaScript editor (see image below).

Use the pencil icon and then tap the +Add Event button to add an entity level disambiguateBagItem function. In the Add Event dialog shown in the image below, select Entity-Level Events.

In the follow-up dialog, select disambiguateBagItem followed by pressing the OK button. 

At this point, the entity event handler contains a function disambiguateBagItem in the entity section. The event argument object provides two properties, matchValue and matchedBagItems, that the implementation code uses to generate the list of values. The context argument grants you access to the entity resolution object to compose custom messages and layouts. 

Create one more function using the + Add Event button. This time select Custom Events to create a custom button payload function.

Select someCustomEvent and use the OK button to add the new event function.

The image below shows the custom event function that I renamed to disambiguationHandler. The custom event is invoked when users select one of the disambiguation options from the list. As you will see later, this function receives the information about which bag item to set and the value to set it to.

The image below shows the code added to the disambiguationBagItem to create the custom implementation of the custom disambiguation dialog.

• Line 29 : gets the default prompt also used in the the default dialog
• Line 31 : starts composing a new text response using the default prompt
• Line 35: iterates over the bag item names that are candidates to receive the user provided value.
• Line 50: To obtain the human readable label of a bag item, the code needs to access the bag item definition, which it can using the bag item name obtained in line 35
• Line 52: For each candidate bag item, the text message is updated with an action item. The action item has two arguments: the human readable bag item label and a custom event definition that references the custom event created earlier. The information passed to the event as arguments are the bag item name and the value to set to the bag item when the user selects a button
• Line 58: The newly composed message is added as the prompt message so the user sees the disambiguation dialog

The custom event code shown in the image below is simple and updates the bag item with the provided user value. 

Finally, running the custom disambiguation event handler in the skill conversation tester, this is what you see.

To save me some time. the skill focuses on the problem at hand (which is the customization). Thus, to see that  the end date bag item got updated, you need to look at the Conversation tab of the conversation tester to see the updated variable (image below)

What to change to make the custom disambiguation dialog even more customized?

Here are the use cases for a custom disambiguation dialog I mentioned earlier

1. Adding an extra button to dismiss the dialog
2. Displaying a prompt conditional to the type of disambiguation (e.g. a date disambiguation would be prompted different than a number disambiguation)
3. Displaying the choices as a carousel of cards instead of a list of values
4. Suppressing the disambiguation dialog and setting the disambiguation value based on custom logic (e.g. if the start date is not set, then always set the date to the start date as an end date does not make sense without a start date)

Based on the image showing the custom disambiguation function, code, the following lines would need to be changed

Usecase 1: Change line 31 with your custom text string. The text can be read from a resource bundles string (recommended) using context.translate('rb_key_name')

Usecase 2: In line 57, add another call to textMessage.addAction(). 

Usecase 3: change line 31 and use a call to mf.createCardMessage( … )

Usecase 4: don't generate any UI but directly call context.setItemValue('bag_item_name', event.matchValue)

Download Sample Skill

Get the sample skill from here. Go to the entity section and explore the entity event handler on the composite bag entity.