The Mobile & Digital Assistant Blog covers the latest in mobile and conversational AI development and engagement

TechExchange Quick-Tip: How to Intelligently Cancel Composite Bag Entity Driven User Dialog Flows

Frank Nimphius
Master Principal Product Manager

article by Frank Nimphius, reposted June 2021


Composite bag entities in Oracle Digital Assistant are a data-driven approach to conversation design. With composite bag entities you group related entities and items like String, Location or Attachment to a logical unit that then get resolved by the System.ResolveEntities and the System.CommonResponse component without you needing to write individual dialog flow states. However, if the conversation is data-driven, you may wonder how users can interrupt e.g. to cancel, exit or simply pause the bot interaction. This article explains an intelligent solution to implement a cancel and exit option to your composite bag entity dialogs that allow users to discontinue a data-driven conversation. 

Why You Should Use Composite Bag Entities

If you, as a digital assistant developer, are not yet using composite bag entities, there are several reasons to consider doing so, including:

  • Composite bag entities promote data driven dialog flows and are the future of conversation design in Oracle Digital Assistant
  • Composite bag entities help reducing the BotML lines of code you need to write for a conversation. Because a single dialog flow state can be used to collect multiple values, you don't need to write so many dialog flow states.
  • Option to include non-entity items of type string, location or attachment. In an expense report, attachments could be used to associate a receipt with an expense item.
  • Ability to conditionally prompt for an item in the composite bag entity. An expense report may not require a receipt to be uploaded if the charged amount doesn't reach a certain threshold. For this, you can define an expression that ensures users are not getting prompted for uploading a receipt.
  • Ability to customize prompts of a system entities referenced by a composite bag item.
  • Composite entity bag items can be configured to be extracted out of sequence, which means that if users provide information that matches an item in the composite bag entity, even though they are not prompted to enter the information, that information is still used to update the matching item. This also means that information previously provided can be changed later in the composite bag entity driven conversation.
  • Composite bag entities support event handlers, allowing you to code complex input validations that may include remote service access using custom components.

To learn more about composite bag entities, see the following tutorial: thttps://docs.oracle.com/en/cloud/paas/digital-assistant/tutorial-entities/index.html

Interrupting Composite Bag Entity User Dialogs

Composite bag entities group related entities and items to a logical unit that get resolved together. Within a composite bag entity, bag items (references to entities, as well as String, Location and Attachment type items) can be extracted out of order and also dependently validated.

For example, when prompted to enter a expense item in an expense bot, a user may type "I want to expense lunch  at Pasta Alfredo in Rome on February 15th 2020 for 15$" when prompted for where the expense occurred. This user input would then no only update the location bag item but also extract values for the amount (15$) and the day (February 15th 20202), so that the user is not prompted for this information. Because the amount of 15$ is less than 25$, your business logic defined in the composite bag entity could then determine not to prompt the user for uploading  a receipt. When prompt for whether the expense contains a tip, the user might answer "the tip was 2$, but the expense actually was in Milan". This the updates the tip bag item but also corrects the location bag item.

As you can tell from the example conversation above, using composite bag entities allows natural conversations between a human and the bot. But what if the user wants to cancel the conversation to start again or to even exit the bot? Well, this is what the remaining of this article explains how to do.

The Sample Dialog

The sample dialog shown in the images below has two data entities grouped in a composite bag entity. The Pastas entity allows you to select a pasta type and the Extras entity allows you to select one or many toppings like garlic, cream and oil. As shown in the image below, at any time when a user gets prompted for input, she could exit the conversation. 

How to Implement Intelligent Dialog Flow Cancelling

Certainly, there are many options you have to implement the behavior shown in the image above. The best implementation, in my opinion, is to add an entity to the composite bag item that handles the user cancel request. So what i am doing in this example is to have composite bag entities containing two types of entities: data entities (Pastas, Extras) and metadata entities (CancelMetadataEntity). While the data entities matter from a business perspective as they collect the information needed for a request or transaction, the metadata entities (which are regular entities too) allow the bot designer to make dialog flow decisions.

Notice the CancelMetadataEntity, which is of type Value List entity. For the example, I added to values with synonyms: "cancel" and "exit". The idea for this entity is that a cancel request and an exit request would be detected in a single value extraction. However, after you learn that the user wants to discontinue the composite bag dialog, you can then use the value of this entity to understand how the user wants this to happen. 

Note: You can add more values and synonyms if you have a usecase for it. E.g. you could use this technique to "pause" a dialog flow conversation temporarily. So adding a "pause" value and synonyms would all the user e.g. to say "I want to complete this later" (synonyms: complete later, complete this later, continue later, ...). When then you detect the pause request, you save the information the user collected so far in a location from where you can resume the conversation.

The nice thing about using entities (like CancelMetadataEntity in this example) to detect a cancel request is that it extracts the requirement from complete sentences. Notice how the cancel option has a synonym "out of here". The message I used to discontinue the request was "hm, no. get me out of here". I could also said "No. Changed my mind, stop". 

In the composite bag entity, the CancelMetadataEntity is added as a bag item. Intentionally I named the bag item "ExitCancel", just to show that bag item names don't need to match the entity name itself. 

The secret of how this works is by setting the following property for the ExitCancel bag item:

By setting the Prompt for Value property to false, the user will not be prompted to provide a value for this bag item. So the only option for the ExitCancel bag item to have a value is when the value gets extracted out of order (!!!). Remember, out of order extraction happens when a value is set though the user is prompted for a different item. 

Note: When you are done creating the composite bag entity, don't forget to train the model. Composite bag entities are smart objects and need to be trained to do their magic.

The final configuration to do is in the dialog flow. As you can see in the image below, the System.ResolveEntities component has its property transitionAfterMatch set to "true" (not the boolean true, but the string"true"). With this setting, whenever an entity contained in a composite bag entity receives a value, the System.ResolveEntities component transitions to the dialog flow state configured for the match transition. In the example, the state is called "checkCancel". 

Note: The same property and transition action exists for the System.CommonResponseComponent


In the checkCancel state, there are two things that need to happen

  • Detect if the outOfOrderMatches attribute of the current entity to resolve (the composite bag entity) contains values
  • Traverse the out of order matches for the ExitCancel bag item name. If you find this, then the user wants to discontinue (Remember that the ExitCancel bag item can only be populated with a value if it is done as an out of order extraction)

Notice how the source property of the System.Switch component uses an Apache FreeMarker expression to detect whether the outOfOrderMatches attribute has a value and if so, if the out of order matches contain a value for the ExitCancel bag item. 

Here's the complete expression:

"<#if system.entityToResolve.value.outOfOrderMatches?size == 1 ><#if system.entityToResolve.value.outOfOrderMatches[0].name == 'ExitCancel'>cancel<#else>none</#if><#else>none</#if>"

Note: "&gt;" needed to be used instead of ">" to avoid a conflict with BotML syntax validation

If you wonder how I knew about the outOfOrderMatches attribute, see the image below, which shows the conversation tester embedded in Oracle Digital Assistant Skills. 

The entityToResolve reference points to the current entity prompted for in a composite bag entity. So when prompted for selecting a pasta, then the current entity is Pastas. Providing information e.g. about Extras to this point in time, would update the Extras entity and lists it as an outOfOrderMatch. 

Because by configuration, the ExitCancel bag has its Prompt for Value property set to false, it is not prompted for at all, it can only be extracted out of order.

Note: You see me reiterating this fact over and over because its the secret key of success for this use case. 

The checkCancel state in the example routes the request to a state named handleUserExit when a cancel request was detected. If no cancel request was detected, then the request is routed back to the System.ResolveEntities component state to prompt users for other bag items. When all bag items have a value set (Pastas and Extras in this example) then the transition follows the next transition. The next transition in the example points to the confirmOrder state to print the order confirmation.

Here's one more image showing the "intelligence" of this solution:


Notice how the handleUserExit state used the information in the outOfOrder match of the ExitCancel bag item to tell whether the user wants to cancel or also exit the conversation.

The Apache FreeMarker expression:

"Order ${(pastaBag.value.ExitCancel == 'cancel')?then('cancelled.','cancelled and conversation exited.')}"

Note: If you added "pause" as another option to discontinue the conversation, then you would need to also check for "pause" as an option. 


You can download the example skill (ODA version 20.x and later) from here (ZIP). Ensure you train the imported skill before testing it by typing "Hi" or "I want to order" 

Related Content

TechExchange: How-to Use the System.ResolveEntities Component in Oracle Digital Assistant

TechExchange Quick-Tip: Understanding Oracle Digital Assistant Skill Entity Properties - Or, What Does "Fuzzy Match" Do?

TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube


Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.