Import the Starter Skill

1. Log into Oracle Digital Assistant.
2. Click in the top left corner to open the side menu.
3. Expand Development and then click Skills.
4. Hide them menu by clicking again.
5. Click Import Skill (located at the upper right).

   

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 () in the left navbar.
2. Click the OrderPizza intent and take a look at its utterances.
3. Click Entities () 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.

   

5. Click Flows () 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).
   
7. Accept the default selections in the Train dialog and then click Submit.
8. Click the Skill Tester in the left navbar.
   
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 ().

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.

Create the Composite Bag Entity

1. Click the Entities () 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.

   

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 () , 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.

    

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.

    

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 ().
2. Select the OrderPizza intent and then click + Entity.
3. Select PizzaBag from the list.
4. Retrain the skill.

   

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 () 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.

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 ( ) 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.

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.

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 () 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 ( ) 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.

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 ( ) 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.
   

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.