Building a Bot

Later on, you'll be updating this dialog flow to give PizzaBot users another option: specifying cheese! But before you get to that point, you'll need to get acquainted with some dialog flow concepts and how they apply to the PizzaBot's dialog flow definition.

Dialog flows have two main parts: the context and the states. You define the variables that are used throughout the dialog flow (that is, through the entire user-bot interaction) in the context section. You can define these variables to hold literals, primitives, or the values extracted from from the user input by the entities.The variables defined for the Pizzabot do just that -- they are defined by the Pizzabot entities that detect the user's preferences from the input text. There's another variable, iResult, that's also defined by an entity called nlpresult. Unlike the other entities in the context declaration, nlpresult is not specific to the PizzaBot. Instead, it's used widely -- you'll see it in almost every reference bot's dialog flow. As its name implies ("nlp" stands for Natural Language Processing), this entity holds the intent that's resolved from the user input. You would probably define a variable for this entity in every flow you write.

The states section follows the variable definitions. States manage the logic within the bot flow. Each state definition is built around a component, which executes some function. At runtime, the Dialog Engine traverses the state nodes from the top-down and executes the components. For the Pizzabot, the first state that the Dialog Engine encounters is called Intent. Like nlpresult, Intent is common to most bot dialog definitions. This state initializes the dialog flow using the intent that's held by the iResult variable to trigger a subsequent state. For the PizzaBot, the possible entry points reflect the two intents already defined for it (OrderPizza: "resolvesize" and CancelPizza: "cancelorder")There's a third outcome, though it's not specific to any PizzaBot intent: unreslovedIntent: "unresolved". This handles the user requests and statements that can't be resolved to either of the other intents. When this happens, the bot outputs "I do not understand. What do you want to do?" in the chat window.

For the Pizzabot, which, as its name implies, handles orders, there are the two intents that you saw earlier: OrderPizza and CancelPizza.

To create these intents:

1. First, click Add Intent.

   

2. By default, Bots calls this first intent Intent1. Rename it OrderPizza.

3. Add these three utterances in the Examples section:

   • can I order a Pizza

   • I feel like eating a pizza

   • I want to order a pizza

     

     The Bot builder adds each statement after click Enter or click outside of the field.

   Tip: You don't need to end your statements with question marks (?) or periods (.).

4. Repeat these steps to add the CancelOrder intent. Add the following utterances for this intent:

   • I don't want the pizza anymore

   • I want to cancel my pizza order

     

You've now provided the basic ingredients that allow your bot to recognize user input for ordering a pizza, but right now, your bot has no cognition. It can't understand any user input.

1. To enable it to use the intents, you need to train one or more of the models. Click Train.

   

   The Train button deactivates after training completes (which is usually less than a second when you train the default model).

   

2. To gauge how accurately the model resolves user input to an intent, click Test to open the test window.

   

3. Click Intents in the test window.

   

4. Enter one of the phrases that you used to define the intent and then click Send.

   

   The model resolves these phrases with 100% accuracy (as long as you stick to your training corpus, that is).

While the model resolves with perfect accuracy for phrases that you've included in your training corpus, the odds become less certain when you enter a variant of one of these phrases, such as "order a pizza."

To improve the intent resolution when your users go "off-script", you need to expand your training corpus, both in terms of its volume and diversity. Typically, you should create about 12 to 24 sample phrases for each intent that can include common expressions, colloquialisms, and even misspellings.

1. While you can add the utterances individually here in the Bot Builder, you can also define them in a CSV file that you later import. To save time, you're going to populate your corpus by following the latter approach using a file called MyPizzaBot-corpus.csv that's included in the accompanying ZIP.

   1. Click More and then choose Import intents.

      

   2. Browse for, and select MyPizzaBot-corpus.csv to populate the sample phrases.

      

   3. Whenever you add a sample utterance, you need to retrain the model, so click Train.

      

2. So far, you've trained the default model, which is rules-based. To allow your bot to predict user input which falls outside of your training corpus, like "Forget this pizza!", you need to train another model called Trainer Tm, which uses a different approach to machine-based learning. To train this model:

   1. Click the menu and then choose Trainer Tm.

      

   2. Click Train.

Now, its time to add entities, which help the intent fulfill a user request by providing vital piece of information. As you saw in the original PizzaBot, the PizzaType, PizzaSize, and PizzaCrust entities enable the OrderPizza intent to complete an order. This step shows you different ways of adding entities: you can populate them by uploading a CSV file like you did when you added the intents, and you can also use the Bot Builder to add them on your own. First, let's import the entities and then find out more about them. If you cloned the bot, then you already have these entities.

To import the entities:

1. Click Entities in the left navbar. Right now, the Entities page lists only the built-in (or system) entities that we provide. They extract generic information from the user input like addresses, dates, and time.

   

2. Click More and then choose Import 'Value list' entities.

   

3. Browse to the extracted ZIP file, and then open the MyPizzaBot-Entities.csv file. You've populated your bot with three new entities: PizzaCrust, PizzaType, and PizzaSize. These are are known as value list entities. By clicking one, you can see that it's comprised of a set of predetermined values, like thick, thin, stuffed, and pan for PizzaCrust. When you have a short list, you can expose these as a list of values, or as a value expression, as you'll see later on.

   

4. Next, add a new list value entity, CheeseType:

   1. Click Add Entity.

      

   2. Rename the entity "CheeseType". In the Configuration section, accept Value list (the default option)

      
   3. Next, add the values themselves along with some synonyms (or in this case, common misspellings) that optimize the entity's ability to tag words from sloppy user input. To do this, click Add Value to open the Create Value dialog and then complete this dialog for each of the following values.

      Value	Synonyms
      Mozzarella	Mozarela, Mozzarela
      Provolone
      Gouda
      Cheddar

      

      When you're done, the Entities page should look like this:

      

5. Here's an optional step: To make the confirmation text look a bit better, change the letter case for the PizzaSize values from uppercase to lowercase:

   1. Select the PizzaSize entity.

      

   2. Select the Large value and then click Edit. While you're here, take a look at the synonyms that allow the entity to match free-form user input.

      

   3. Using the Editing Value dialog, change the letter casing and then click Update.

      

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

      
6. The OrderPizza intent only needs these entities to complete the user requests. it doesn't use any of the built-in entities, so you don't want intent to waste time by iterating through the ones that it doesn't need. Instead, you can limit it to just the custom entities that you've added by doing the following:

   1. Click Intents in the left navbar and then select OrderPizza (if it's not already selected).

      

   2. Click Add Entity.

      

      Tip: If the test window is still open, close it by clicking Test.

   3. Scroll through the list, and select CheeseType from the list.

      

   4. Repeat this for PizzaSize, PizzaType, and PizzaCrust. When you're done, the page should look like this:

      

Since you added the CheeseType entity, you need to update the flow to enable the bot to present this new option. Since you need to slot user values for the cheese type, you need first declare the variable, set the value and then define a state for a list component.

1. You can declare variables as a literal, a primitives, or as in this case, an entity -- the CheeseType entity. You need to declare this variable within the context section because it's referenced in a couple of different places in the dialog flow: first to check if any value entered by the bot user matches any of the values that you added to the entity (Mozzaella, Cheddar, etc.) and then later on where bot presents the user with the cheese options.

   Within the context section of the dialog flow add cheese: "CheeseType" after the crust variable. Be sure that the value matches the entity name exactly. If you enter "Cheesetype" instead of "CheeseType", you'll get an error.

   

2. Next, add the state that verifies the user input against the CheeseType definition. Because the flow is basically sequential, you need to add this state somewhere after the intent state, whose System.Intent component initializes the dialog flow, but before you prompt users to select some type of cheese from a list of options (the cheese state, which you'll add in the next step), or the checkAge and askAge states that verify the user's age (and fork the dialog flow accordingly). For the revised sequence, add this new state to the ones that define the System.SetVariable using a value expression to user input for pizza size, crust, and pizza type.

   To add this state to the flow:

   1. You don't want to add this above the first of these states, resolvesize, because the intent state already defines that state as the starting point of the dialog flow (OrderPizza: "resolveSize"). Instead, add it to end of this group by positioning your cursor after the transitions{} property of the resolveType state.

      

   2. Click Add Components (located at the top of the page).

      

   3. Choose Set variable.

      

      Bots generates a scaffold state node for a System SetVariable component.

      

   4. Define the state as follows:

      • Change the state name from setVariable to resolvecheese.

      • Define the variable property as "cheese"(a literal value).

      • Define the value property by copying in the following value expression. It uses the iResult variable (another variable declared in the context section used to hold the results of resolved intents and entities) to set the value for the cheese variable. The CheeseType entity is associated with the OrderPizza intent, which is resolved by Intent component. For example, this expression sets the cheese variable to any value that's extracted from the user input by the CheeseType entity.

        "${iResult.value.entityMatches['CheeseType'][0]}"

      • Finally, click Return to create a new space after the value property and then insert transitions: {}. As noted by the empty brackets ({}), this state moves directly onto the asksage state.

        

        Important: Be sure that you indent transitions so that it's at the same level as properties. To ensure that the OBotML syntax is valid, click Validate whenever you make changes to the dialog flow.

   As an alternate approach, you can paste this code block directly into the dialog flow.

   resolvecheese:
       component: "System.SetVariable"
       properties:
         variable: "cheese"
         value: "${iResult.value.entityMatches['CheeseType'][0]}"
       transitions: {}  

3. Next, add the state that prompts the user for input using the System.List component.

   1. First, position your cursor after the transitions {} definition in the type state (which is right above the done state).

      

   2. Click Components and then select List.

      

      Your dialog flow now includes a scaffolding for a state node for a System.List component.

      

   3. Configure the state as follows:

      • Change the state name from list to cheese.

      • You have two choices for defining the options property: you add literals ("Mozzarella,Provolone,Gouda,Cheddar") or a value expression that calls the variable values: "${cheese.type.enumValues}".

      • For the prompt, enter a text string like "What kind of cheese do you want?".

      • Enter "cheese" as the variable.

      • You can delete or ignore the maxPrompts property.

      • Complete the state by clicking Return to create a new line after the variable property and then by adding transitions {}. Again, there are no actions defined because the dialog moves on next state, one that prompts the bot user for enter the pizza type before confirming the order.

        

      • To make sure that these additions adhere to the YAML spacing conventions, click Validate.

        

        The code for defining options with literals looks like this:

          cheese:
            component: "System.List"
            properties:
              options: "Mozzarella,Provolone,Gouda,Cheddar"
              prompt: "What kind of cheese do you want?"
              variable: "cheese"
            transitions: {} 

        The code for the value expression options definition looks like this:

          cheese:
            component: "System.List"
            properties:
              options: "${cheese.type.enumValues}"
              prompt: "What kind of cheese do you want?"
              variable: "cheese"
            transitions: {}

4. Finally, update the confirmation message to include both the cheese preference ${cheese.value}and crust type (${crust.value}, which wasn't included in the original PizzaBot message) to the text property in the done state:

   1. Go the text property in the done state.

      

   2. Add ${crust.value} to the definition.

   3. Add ${cheese.value} to the definition.

   4. If you like, you can reword the message to accommodate these new additions. For example, change the text property to "Your ${size.value}, ${type.value} pizza with ${crust.value} crust and ${cheese.value} cheese is on its way."

      

      The code for the done state looks like this:

      done:
          component: "System.Output"
          properties:
            text: "Your ${size.value}, ${type.value} pizza with ${crust.value} crust and ${cheese.value} cheese is on its way."
          transitions:
            return: "done"

You might have noticed by now that along with the CheeseType entity, the PizzaCrust and PizzaSize entities are exposed as list of values (LOV) in the chat. LOVs work well for entities like these, which have have only a few values each. But for an entity like PizzaType, which has a number of values, LOVs become cumbersome in the small chat window. Because of this, the type state uses the System.Text component to prompt the user to enter a value rather than pick one from a list. If you want the type state to output a list instead, substitute the following code:

  type:
    component: "System.List"
    properties:
      prompt: "What Type of Pizza do you want?"
      options: "${type.type.enumValues}"
      variable: "type"
    transitions: {}