Oracle by Example brandingEnable Real-World Entity Extraction with Composite Bag Entities

section 0Before You Begin

This 45 minute tutorial shows how you can easily add value-setting logic with the composite bag entity.

Background

In this tutorial, you're working with a skill for ordering pizzas that has a basic dialog flow definition along with some intents and entities for extracting values for the pizza order, delivery address, and delivery location. By adding a composite bag entity to these building blocks, you can create a pizza skill that allows spontaneous, real-world interactions without having to implement custom code or write a complex and lengthy dialog flow definition. How and when the composite bag sets the values for these entities depends on the circumstance. When customers change their orders midway through the conversation, for example, the skill can gracefully update the previously extracted value and continue on without forcing them to begin their orders all over again. The skill can prompt for values when they're not included in the customer input and can validate this input as well, sending context-specific error messages when it's incorrect.

What Do You Need?

  • Access to an Oracle Digital Assistant instance.
  • The PizzaBot_Materials.zip file, which includes the starter skill, reference files, and a finished version of the skill. Click here to download this file and then unzip it to your local system.

section 1Explore the Starter Skill

The first thing you need to do is import the starter pizza skill into your Oracle Digital Assistant instance so that you can see what you're working with.

Import the Starter Skill

  1. Log into Oracle Digital Assistant.
  2. Click menu icon in the top left corner to open the side menu.
  3. Expand Development and then click Skills.
  4. Hide them menu by clicking menu icon again.
  5. Click Import Skill (located at the upper right).
    An image of Skills dialog box with the Import Skill button highlighted.
    Description of the illustration import_skill.png.
  6. Browse to, and then select, CompositeBagTutorial_Starter.zip. Then click Open.

Explore and Test the Skill

Take a look at the intents and entities.

  1. In the dashboard, click the CompositeBag_Tutorial_Starter tile to open skill in the Skill Builder. The intent editor should be selected when this development environment is launched. If it isn't, click Intents (Intent icon) in the left navbar.
  2. Click the OrderPizza intent and take a look at its utterances.
  3. Click Entities (Entities Menu Icon) in the left navbar.
  4. Click the PizzaDough, PizzaSize, PizzaTopping, and NamedLocation entities. Take a look at the values and synonyms defined for each of these Value List entities. Notice that PizzaTopping and PizzaSize entities both have prompts.
    An image of the list of entities associated wiith the Pizza entity.
    Description of the illustration pizzas_entities_list.png.
  5. Click Flows (The dialog flow editor icon) in the left navbar. Notice that at this point, it's just a basic flow. We're going to add the code to resolve the various pizza variables in a minute.
  6. Click Train (located on the right side of the top menu).
    The Train button
  7. Accept the default selections in the Train dialog and then click Submit.
  8. Click the Skill Tester in the left navbar.
    Skill Tester icon
  9. In the chat window, enter I want a pizza and then click Enter. The skill replies with the placeholder message (This is where you will see the pizza order) that's the value for the showPizzaOrder component. Throughout this tutorial, you'll update this message with Apache FreeMarker expressions that allow it to display specific entity values.
  10. Click Reset (located at the upper left of the Skill Tester) to clear your input and then Close (The Close icon).

What you just did: You've imported the basic skill into your instance and tested it to find out if its intent, entity, and dialog flow definitions are valid.


section 2Create the Basic Composite Bag Entity

The first step is to create the composite bag itself, add the PizzaSize and PizzaType entities to it, and then add context-specific prompts and input validators for these entities.

Create the Composite Bag Entity

  1. Click the Entities (Entities Menu Icon) in the left navbar and then click + Entity.
  2. Change the entity name from Entity1 to PizzaBag.
  3. Choose Composite Bag from the Type menu.
    An image of the of the add entity dialog.
    Description of the illustration pizza_entities_configuration.png.
  4. Click + Bag item.
  5. In the Name field, replace BagItem1 with PizzaSize.
  6. Choose PizzaSize from the Entity Name list.
  7. The PizzaBot Skill needs to resolve the size of a pizza, but it also needs to output error messages when customers continually reply with values that can't be resolved by the PizzaSize entity's list items or synonyms. To do this, first increment Maximum User Input Attempts to 3.
  8. Replace the existing error message (Oops I didn't understand, I need a pizza size of small, medium or large) with Sorry, this is not a valid pizza size.
  9. Next, add a sequence of prompt messages that correspond to the allotted input attempts. Each of these messages becomes more emphatic as the sequence progresses. The skill already has the first one (What size pizza would you like?), but it doesn't have a sequence number. To add one, click Edit (The Edit Icon) , enter 1 and then click Enter.
  10. Click Add Prompt.
  11. Enter Please choose small, medium, or large.
  12. Click Add Prompt.
  13. Enter OK! Let's have one more go at this. I just need you to select a pizza size. We offer large, medium and small.
    An image of the of prompt sequence.
    Description of the illustration prompts.png.
  14. Click Close.
  15. The skill resolves the topping type with its PizzaTopping entity. In addition to extracting this value, the skill needs check that the customers has selected only one topping. No substitutions allowed! Before you can add this validation to the PizzaTopping entity, you need to add it to the composite bag. Click + Bag item.
  16. Replace BagItem1 with PizzaTopping in the Name field, then select PizzaTopping from the Entity Name list.
  17. Switch on Prompt for Disambiguation.
  18. In the Disambiguation Prompt field, enter Sorry, you can only order one topping type.
    An image of the Disambiguation Resolution options.
    Description of the illustration disambiguation_prompt.png.
  19. Click Close.

What you just did: You have created a composite bag entity that resolves pizza size and pizza topping through context-specific prompts and error messages.

Associate The Composite Bag Entity to an Intent

In this step, you will add the composite bag entity to the OrderPizza intent to enable the skill to parse the entity values with the intent.

  1. Select the intent icon (Intents Menu Icon).
  2. Select the OrderPizza intent and then click + Entity.
  3. Select PizzaBag from the list.
  4. Retrain the skill.
    An image of the of the configuration dialog specifying the name and configuration type of the PizzaBag entity.
    Description of the illustration pizza_bag_entity.png.

Update the Dialog Flow to Reference the Composite Bag Entity

Next, update the dialog flow with the PizzaBag entity. You need to declare a context variable for this entity and also add a definition for the System.ResolveEntities component, which tracks the values set for the setting for the entities in the PizzaBag.

  1. Click Flows (Dialog flow editor icon) in the left navbar.
  2. In the editor, add a new context variable for the PizzaBag entity by entering pizza: "PizzaBag" directly beneath the iResult variable. Be sure to align this entry with the iResult variable (which is indented by four spaces):
    context:
      variables:
        iResult: "nlpresult"
        pizza: "PizzaBag"   
                       
  3. Click Validate to make sure that you've indented this entry correctly.
  4. Uncomment the resolveEntities state, which contains the System.ResolveEntities component:
      resolveEntities:
        component: "System.ResolveEntities"
        properties:
          variable: "pizza"
          nlpResultVariable: "iResult"      
          maxPrompts: 5
          cancelPolicy: "immediate" 
        transitions:
          actions:
            cancel: "maxError"
            next: "showPizzaOrder"
  5. Click Validate to check the indentation.
  6. Take note of the cancelPolicy property and the cancel action that handle the customer replies that don't provide the kind of values needed to resolve all of the entities within the composite bag, or are completely off-topic. When the input is valid, the System.ResolveEntities component routes to the showPizzaOrder state.
  7. In the showPizzaOrder state, replace the text property definition ("This is where you will see the pizza order.") with a confirmation message, one that returns the entity values using Apache FreeMarker expressions:
    "Ok, so we are getting you a ${pizza.value.PizzaSize?lower_case} ${pizza.value.PizzaTopping?capitalize} pizza."

    When you're done, the showPizzaOrder state should look like this:

      showPizzaOrder:
        component: "System.Output"
        properties:
          text: "OK, so we are getting you a ${pizza.value.PizzaSize?lower_case} ${pizza.value.PizzaTopping?capitalize} pizza."
        transitions: 
          return : "showPizzaOrder"

Validate the Updated Pizza Skill

Let's validate the changes and retrain the skill.

  1. Click Validate to check the indentation. If you're encountering syntax errors that you can't fix, replace the entire the dialog flow definition with the one in the first_cb_dialog_flow.txt file and try validating again.
  2. Click Train.
  3. Accept the default selections in the Train dialog and then click Submit. Wait a moment for the training to complete.

Test the Entity Resolution

Let's test the logic that we've configured for the PizzaSize and PizzaTopping entities and the updated dialog flow.

  1. Open the Skill Tester in the left navbar.
  2. In the chat window, enter I want to order a medium pizza.
  3. When prompted, enter a pizza type and then confirm that both this entity value and medium are included in the confirmation message. Click Reset.
  4. Enter both entity values in the same request by entering I want to order a large veggie pizza. The skill should reply with the confirmation message, which includes both of the entity values. Click Reset.
  5. Try out the error messages by first entering I want to order a pizza.
  6. When prompted for a pizza size, enter a invalid value like huge.
  7. Enter massive.
  8. Enter monster. The skill should reply with the error message and with all three prompt messages. When you've reached the third attempt (the number you set for the Maximum User Input Attempts property), the System.ResolveEntities component triggers the cancel transition, routing you to maxError state. At this point, the skill outputs "OK! Let's connect you with someone to help!" This is just an output message; there's no skill-human agent integration configured for this skill.
  9. Click Reset.
  10. Next, test the value disambiguation by entering two different topping types in one message. For example, enter I want to order a meaty veggie pizza. The skill recognizes the invalid input by replying with "Sorry, you can only order one topping type."
  11. Click Reset, then close the Tester.

section 3Set a Default Value

Now that the basic composite bag implementation works, you can set a default value for the PizzaDough entity. This entity extracts values for two types of dough: regular and gluten-free. To speed the ordering process, we'll assume that most customers prefer regular crust. This will be the default value that's set for the PizzaDough entity. But when customers request gluten-free, the skill updates the PizzaDough entity value. The change is seamless (and invisible) to customers because they receive no prompts or confirmation messages. The crust request is noted and the composite bag prompts for the next entity. For your skill to handle this change, you need to configure the PizzaDough entity to accept gluten-free as an optional value.

  1. Click Entities (Entities Menu Icon) in the left navbar, then select the PizzaBag entity.
  2. Click + Bag item, then replace BagItem1 with PizzaDough.
  3. Select PizzaDough from the Entity Name list.
  4. In the Extraction Rule section, ensure that Out of Order Extraction is switched on.
  5. Enter false in the Prompt for Value field.
  6. Click Close.
  7. Click Train.

What you just did: You've enabled the composite bag to accept customer input that overwrites a default value.

Implement the Default Value Logic in the Dialog Flow

Because gluten-free is the exception, not the rule for most of the skill's customers, you need to update the dialog flow that sets the default value, regular.

  1. Click Flows (Dialog flow editor icon ) in the left navbar.
  2. Update the transition routing in the resolveEntities state by replacing return: "showPizzaOrder" with next: "setPizzaDough".

    When you're done, the resolveEntities state should look like this:

      resolveEntities:
        component: "System.ResolveEntities"
        properties:
          variable: "pizza"
          nlpResultVariable: "iResult"      
          maxPrompts: 5
          cancelPolicy: "immediate" 
        transitions:
          actions:
            cancel: "maxError"
            next: "setPizzaDough"
  3. You've now defined that when the composite bag has resolved all of the values, the dialog will then navigate to the setPizzaDough state. This state keeps the valid values for the PizzaRough entity. When these values aren't valid, it uses the regular value. Add this state directly after the resolveEntities state.
      setPizzaDough:
        component: "System.SetVariable"
        properties:
          variable: "pizza.PizzaDough"
          value: "${pizza.value.PizzaDough?has_content?then(pizza.value.PizzaDough,'regular')}"
  4. Update text property in the showPizzaOrder state to include the dough type by adding This will be on our ${pizza.value.PizzaDough} crust.

    When you're done, the showPizzaOrder state should look like this:

      showPizzaOrder:
        component: "System.Output"
        properties:
          text: "OK, so we are getting you a ${pizza.value.PizzaSize?lower_case} ${pizza.value.PizzaTopping?capitalize} pizza. This will be on our ${pizza.value.PizzaDough} crust."
        transitions: 
          return : "showPizzaOrder"
  5. Click Validate to check for indentation and syntax errors. If you're encountering problems that you can't fix, replace the dialog definition with second_cb_dialog_flow.txt file.
  6. Retrain your skill.

Test the Default Values

Test the new functionality:

  1. Open the Skill Tester in the left navbar.
  2. Enter I want to order a large veggie pizza. The skill confirms your order with regular crust.
  3. Enter I want to order a veggie gluten-free pizza. The skill prompts you for the size. After you select that, the order confirmation includes gluten-free crust.
  4. Click Reset, then close the Tester.

What you just did: You configured the PizzaDough entity so that it can accept an optional value. In the dialog flow, you added a Apache FreeMarker expression that sets regular as default crust type using the has_content and then operators.


section 4Validate the Delivery Time

Part of the pizza ordering process is allowing customers to specify their preferred delivery time. But this PizzaBot doesn't offer 24-hour delivery--it must recognize when customers request a delivery time that's outside of normal business hours and then prompt for valid time. There's no existing entity to recognize time, so you're going to add one to the bag. Unlike the existing entities, this entity is not a Value list. It's based on the built-in TIME entity that recognizes hours, minutes and seconds.

  1. Click Entities (Entities Menu Icon) in the left navbar, the select the PizzaBag entity.
  2. Click + Bag item, then replace BagItem1 with DeliveryTime.
  3. Select TIME from the Entity Name list.
  4. Increment Maximum User Input Attempts to 3.
  5. Add two prompts. Enter When can we deliver that for you? for the first prompt in the sequence. For the second, enter If you can, let us know the delivery time. We close by 10pm.
  6. Click Add Validation Rule.
  7. Enter ${(pizza.value.DeliveryTime.hrs?number < 10)?then('true','false')} in the Expression field.
  8. In the Error Message field, entry Sorry, we only offer delivery up to 9:30 pm.
    An image of the of the DeliveryTime prompts and error messages.
    Description of the illustration time_prompts_errors.png.
  9. Click Close.
  10. Click Flows (Dialog flow editor icon ) in the left navbar.
  11. Update the confirmation message to output the customer's delivery time by adding the following to the text property (after the PizzaTopping expression):

    at ${pizza.value.DeliveryTime.date?long?number_to_time?string('HH:mm')}

    When you're done, the text property definition should look like this:

    "OK, so we are getting you a ${pizza.value.PizzaSize?lower_case} ${pizza.value.PizzaTopping?capitalize} pizza at
     This will be on our ${pizza.value.PizzaDough} crust."

    The showPizzaOrder state should look like this:

      showPizzaOrder:
        component: "System.Output"
        properties:
          text: "OK, so we are getting you a ${pizza.value.PizzaSize?lower_case} ${pizza.value.PizzaTopping?capitalize} pizza at ${pizza.value.DeliveryTime.date?long?number_to_time?string('HH:mm')}. This will be on our ${pizza.value.PizzaDough} crust."
        transitions: 
          return : "showPizzaOrder"
    
  12. Click Validate to check for indentation and syntax errors.

Test the Date Validation

Test how the skill recognizes valid delivery times based on the expression:

  1. Open the Skill Tester in the left navbar.
  2. Enter I want to order a large veggie pizza. The skill replies with "When can we deliver that for you?" (the first prompt in the sequence).
  3. Enter 10 (omitting the am and pm). The skill replies with the second prompt, "If you can, let us know the delivery time. We close by 10pm."
  4. Enter 10pm. The skill replies with your error message, "Sorry, we only offer delivery up to 9:30 pm."
  5. Enter a valid time, like 8pm. The skill notes the delivery time in the confirmation message.
  6. Click Reset, then close the Tester.

What you just did: You configured the DeliveryTime entity so that it not only prompts for a delivery time, but also validates that input because of the comparison operators in the Apache FreeMarker expression.


section 5Extract Entity Values When They're Entered Out-of-Order

Customers shouldn't have to start over when they change their orders. In this step, you configure the entities and the dialog flow , you can implement functionality within the entities and the dialog that will understand if the user re-enters any entity value and to update that value and acknowledge to the users input.

  1. Click Entities (Entities Menu Icon) in the left navbar, then select the PizzaBag entity.
  2. Make sure that Out of Order Extraction is switched on for both the PizzaSize and PizzaTopping entities. Click Edit (The Edit Icon) to open these entities.
  3. Click Close after you've checked the entities.

What you just did: By ensuring that the Out of Order Extraction option is set for both of these entities, you've given the composite bag the flexibility to reset values. Here, the Out of Order Extraction option allows the skill to replace the existing pizza size value. It can be reset at any point.

Test Out-of-Order Entity Extraction for the Pizza Size and Pizza Topping Values

Let’s test how this functionality works.

  1. Open the Skill Tester in the left navbar.
  2. Enter I want to order a large pizza.
  3. When prompted for pizza topping, enter veggie please, but can you make it a medium.
  4. Complete the order process. Make sure that the confirmation message includes medium pizza, not large.

Configure the Immediate Confirmation of the Value Change

Now that you have configured the logic within the composite bag entity to update the pizza size value, you need to skill to immediately acknowledge this change. To do this, you need to add functionality to confirm the change before prompting for the next item value.

First, add descriptions for the PizzaBag and PizzaSize entities:

  1. Click Entities (Entities Menu Icon) in the left navbar, then select the PizzaBag entity.
  2. For the PizzaSize entity, enter size of pizza in the Description field. Then click Close.
  3. For the PizzaTopping entity, enter pizza topping in the Description field. Then click Close.

Next, update the resolveEntities state:

  1. Click Flows (Dialog flow editor icon ) in the left navbar.
  2. In the resolveEntities state, update the System.ResolveEntities component with the following headerText property:

    headerText: "<#list system.entityToResolve.value.updatedEntities>I have updated the <#items as ent>${ent.description}<#sep> and </#items>. </#list>"

    When you're done, the resolveEntities state should look like this:

      resolveEntities:
        component: "System.ResolveEntities"
        properties:
          variable: "pizza"
          nlpResultVariable: "iResult"      
          maxPrompts: 5
          headerText: "<#list system.entityToResolve.value.updatedEntities>I have updated the <#items as ent>${ent.description}<#sep> and </#items>. </#list>" 
          cancelPolicy: "immediate" 
        transitions:
          actions:
            cancel: "maxError"
            next: "setPizzaDough"
  3. Click Validate to check for indentation and syntax errors.

What you just did: You added entity descriptions that are mined by the Apache FreeMarker directive that defines the headerText property. The list directive iterates through the entities using the system.entityToResolve.value.updatedEntities system variable. The values are stored using the ent loop variable. The skill displays the header message that confirms the change before it prompts the customer for the next entity in the composite bag.

Test the Confirmation Alert

Let’s test how this functionality works.

  1. Open the Skill Tester.
  2. Enter I want to order a large pizza.
  3. Enter veggie please, but can you make it a medium. The skill replies with "I have updated the size of pizza."
  4. Click Reset and then close the Tester.

section 6Allowing Related Terms for an Entity Value

In addition the delivery time and the pizza itself, the pizza bot needs values for the delivery address. To capture these values, the skill already has a Value List entity called NamedAddress, which represents the different ways a user might realistically refer to an address without actually specifying the physical address. In addition to these list items, the skill needs a second entity that allows it to recognize an actual street address. On top of that, it needs to resolve both of these related entities using a single user message. A message containing home, for example, resolves both entities.

First, create the entity for the street address and then add it to the composite bag:

  1. Click Entities (Entities Menu Icon) in the left navbar, then select the PizzaBag entity.
  2. Click + Bag item.
  3. Replace BagItem1 with DeliveryAddress.
  4. Select ADDRESS from the Entity Name list.
  5. If you're building this skill with Version 19.1.3 of Digital Assistant, enter ${!pizza.value.NamedLocation?has_content}in the Prompt for Value field. This Apache FreeMarker expression enables the composite bag to prompt only when there's no value extracted for the NamedLocation entity. If you're using Version 19.1.5, then you can skip this step.
    An image of the of the DeliveryAddress Out of Order Extraction option.
    Description of the illustration prompt_for_extraction.png.
  6. Click Add Prompt and then enter What address can we send that to?
  7. Click Close.

Next, add the NamedLocation entity to the bag:

  1. Click + Bag item and then replace BagItem1 with NamedLocation.
  2. Select NamedLocation from the Entity Name list.
  3. Select DeliveryAddress from the Extract With list.
  4. Enter false in the Prompt for Value field.
  5. Click Close.
    An image of the of the NamedAddress Out of Order Extraction option.
    Description of the illustration out_of_order_extraction.png.

What you just did: You've added two related entities to the composite bag that give customers the flexibility of entering the same information in two different formats. You linked these two entities by naming DeliveryAddress in the NamedLocation's Extract With option.

Implement the Extract With Functionality in the Dialog Flow

You now need to update confirmation message to output a hard-coded address only when the customer input contains home.

  1. Click Flows (Dialog flow editor icon ) in the left navbar.
  2. In the showPizzaOrder state, update confirmation message with the delivery address by adding the following Apache FreeMarker expression to the text property definition:
    We are delivering to ${pizza.value.NamedLocation?has_content?then('Buckingham 
    Palace, The Mall, Westminster, London SW1A 1AA',pizza.value.DeliveryAddress.originalString)}

    When you're done, the showPizzaOrder state should look like this:

      showPizzaOrder:
        component: "System.Output"
        properties:
          text: "Ok, so we are getting you a ${pizza.value.PizzaSize} ${pizza.value.PizzaTopping} at ${pizza.value.DeliveryTime,date? long? number_to_time?string('HH:mm')}. This will be on our ${pizza.value.PizzaDough} crust. We are delivering to ${pizza.value.NamedLocation?has_content?then('Buckingham Palace, The Mall, Westminster, London SW1A 1AA',pizza.value.DeliveryAddress.originalString)}"
        transitions: 
          return : "showPizzaOrder"
  3. Click Validate.

What you just did: For the sake of testing, you set a hard-coded address which represents the home address for the logged in user (and for the sake of simplicity, we added a hard-coded office address). The composite bag will recognize that home is a valid value and accept it. When it prompts for the address, the skill only allows a valid address, or a phrase, such as "home delivery please" that either includes the word home or one of its synonyms defined for the NamedAddress entity.

Test the Extract With Functionality

Let's test how this functionality works.

  1. Open the Skill Tester in the left navbar.
  2. Enter I want to order a large veggie pizza for 9pm. The skill replies with "What address can we send that to?" (the prompt for the DeliveryAddress entity).
  3. Enter any address. For example, enter 1313 Mockingbird Lane. Note that the confirmation message includes the address that you entered. Click Reset.
  4. Enter I want to order a large veggie pizza for 9pm again, but when prompted for an address, enter home delivery please. Note that skill maps home to the hard-coded address. If you replied with something like, My mate, Dave's (an invalid value, one that's neither a NamedAddress value or an actual address), the skill prompts with "What address can we send that to?" until you enter an address or home.
  5. Click Reset, then close the Tester.

section 7Enhance Error Messages

Currently, the error message for the PizzaSize entity is static. It doesn't let the customer know what's going wrong. To output messages that reflect the incorrect user input, you need to update the entity's error message with an Apache FreeMarker expression.

  1. Click Entities (Entities Menu Icon) in the left navbar and then open the PizzaBag entity.
  2. Select the PizzaSize entity and then click Edit.
  3. Update the Error Message text with the following Apache FreeMarker expression:

    '${system.entityToResolve.value.userInput!'this'}'

    When you're done, the message will be:
    Sorry, '${system.entityToResolve.value.userInput!'this'}' is not a valid size of pizza.

    An image of the of the error message text pane showing the new error message for invalid pizza size.
    Description of the illustration_error_message.png.

What you just did: You've implemented "reflective listening” approach by adding the Apache FreeMaker expression with the system.entityToResolve.value.userInput property.

Test the Rich Error Messaging

Let’s do one final test.

  1. Open the Skill Tester from the left navbar.
  2. Enter I want to order a veggie pizza for 9pm.
  3. When the skill replies with the first prompt in the sequence ("What size of pizza would you like?"), enter huge. Because of the userInput property that's appended to the system.entityToResolve.value variable in the expression, the skill replies with "Sorry, huge is not a valid size of pizza. Please choose small, medium or large pizza."

Well done! Your skill can set and reset values. By validating the customer input, it's also less error-prone.


more informationWant to Learn More?