FormFlow In Microsoft Bot Framework - Part One

In this series we are going to explore a few basic and advanced features of formflow in Microsoft bot framework. In Part 1 we will see what formflow is, and how to implement a basic formflow.

In the next part we will see how to dynamically assign values for form fields and we will also see how to display the field options as Hero card in Carousel format.

Prerequisites

• Basic knowledge of chat bot and Microsoft bot framework.
• Visual studio community 2017 + Bot Application template installed.
• Bot framework emulator installed.

What is Bot framework?

While chat bot is one of the most emerging technologies nowadays, Microsoft provides a very powerful framework to create  bots and to publish them across multiple channels such as Skype, Facebook Messenger, Slack etc. Since I would like to concentrate more on formflow in this post thus not going into much details about the basics of bot framework. To know more about bot framework please refer to the following introductory articles.

• What is Microsoft Bot Framework Overview
• Getting started with the Microsoft Bot Framework The Microsoft Bot Framework provides just what you need to build and…blogs.msdn.microsoft.com

Without wasting much time let's proceed to Formflow basics first and why it's important.

What is Formflow ?

FormFlow is a Bot Builder SDK library that lets you declare the type of information you need and then it does the bulk of the work of managing the conversation and moving the user from question to question automatically. Basically with this tool you can create a well defined guided conversational application on the fly with tons of features that come out of the box.

With Formflow, Microsoft does most of the heavy lifting for us. Such as it provides prompts for fields, clarifies ambiguity, shows progress at each step, gives us ability to go back and much more. While most of these features comes out of box, Microsoft provides us with scope for modification and customizing our form.

Here is a list of features that comes out of the box in form flow,

• Provide clear help and guidance.
• Understands both number and textual entries.
• Gives feedback on what is understood or not.
• Asks clarifying question when required.
• Allows navigation between steps.
• Custom prompts per field.
• Template to use when automatically generating prompts or help for fields.
• Terms to match on.
• Supports optional and conditional fields.
• Value validation.

To know more about the basics of formflow and a good example please visit the official Microsoft documentation below.

• Basic features of FormFlow
• Dialogs are very powerful and flexible, but handling a guided conversation such as ordering a sandwich can require a…docs.microsoft.com

For customization Microsoft provides three main ways to do that:

1. Attributes: Items that you can add to your class to better control your dialog.
2. Custom business logic: Logic for setting and getting custom values.
3. Form builder class: Allows for most amount of fine grained control.

For more details on customization please visit the Microsoft documentation below.

• Advanced features of FormFlow
• Basic features of FormFlow describes a basic FormFlow implementation that delivers a fairly generic user experience. To…docs.microsoft.com

Now that we have see the basic and few advanced features we will dig deeper into some more customization in formflow.

In order to understand Dynamic Formflow lets first start with Basic Formflow and see how it works with a simple example.

Basic FormFlow

Lets use a simple Restaurant bot for this example.

Step 1 - Creating the Formflow form

A Form in botframework is a class with fields and/or properties to hold the information you need. Let us now proceed to a demo, for the demo I will use a very basic food ordering use case with predefined menu items that user can select and place their order with few other information.

For the simple Restaurant demo, we just need to know the selected MenuItems, Deliverymode, UserName, PhoneNo and address, as shown in the following code.

[Serializable]
public class OrderDetails {
    public List < MenuOptions > Items {
        get;
        set;
    }
    public DeliveryOptions DeliveryMode {
        get;
        set;
    }
    public string UserName {
        get;
        set;
    }
    public string Phone {
        get;
        set;
    }
    public string address {
        get;
        set;
    }
}
// This starts at 1 because 0 is the "no value" value
public enum DeliveryOptions {
    TakeAway = 1,
        Delivery
}
public enum MenuOptions {
    CrispyChicken = 1,
        ChickenWings,
        ChickenDrumStick,
        ChickenPopcorn
}

So this is a very basic formflow form which we can use to create a conversation between the bot and its users for ordering some item in a restaurant.

As you can see the main class is marked by [Serializable] attribute to properly maintain state. The property are of type string and enum. Property of type string means it will accept any string input from the user when user is prompted for any such property.

On the other hand there are two property which has enum types. Which means those properties will be prompted with choice or options that are there in the enum.

Now as stated earlier a whole lot of customization is possible in formflow but we will first stick to the very basic and see how this form performs.

Step 2 - Configuring the form

To make the OrderDetails class a form, instantiate a FormBuilder with its type. In our case we will initialize a from of type OrderDetails. Here’s a basic example of how to do that.

public static IForm < OrderDetails > BuildForm()
{
    return new FormBuilder < OrderDetails > ().Message("Welcome to demo Restaurant bot!").OnCompletion(async (context, order) =>
    {
        await context.PostAsync("Thanks for your order!");
    }).Build();
}

The BuildForm method returns a FormBuilder<OrderDetails> instance. The FormBuilder gives us a fluent interface, where we can chain several methods together. Message shows a message to the user, which is when the bot starts communicating. FormBuilder will manage the conversation, using the OrderDetails class.

To know more about formbuilder and the several methods that are available to add to the chain please visit the official documentation here.

When the bot finishes, the lambda passed to OnCompletion communicates with the user again. This is where we could take action to do something with the report, like save it in a database or submit to a Web service. The context is the DialogContext and the lambda uses context to send a final message to the user. The lambda’s order parameter holds the OrderDetails class instance, holding the state that FormFlow collected, which you can use to extract user answers.

I have put the BuildForm method inside the OrderDetails class. Lets take a look at the complete class with the required packages.

using Microsoft.Bot.Builder.FormFlow;
using System;
using System.Collections.Generic;
using Microsoft.Bot.Builder.Dialogs;
namespace RestaurantDemo.Model {
    [Serializable]
    public class OrderDetails {
        public List < MenuOptions > Items {
            get;
            set;
        }
        public DeliveryOptions DeliveryMode {
            get;
            set;
        }
        public string UserName {
            get;
            set;
        }
        public string Phone {
            get;
            set;
        }
        public string address {
            get;
            set;
        }
        public static IForm < OrderDetails > BuildForm() {
            return new FormBuilder < OrderDetails > ().Message("Welcome to demo Restaurant bot!").OnCompletion(async (context, order) => {
                await context.PostAsync("Thanks for your order!");
            }).Build();
        }
    }
    // This starts at 1 because 0 is the "no value" value
    public enum DeliveryOptions {
        TakeAway = 1,
            Delivery
    }
    public enum MenuOptions {
        CrispyChicken = 1,
            ChickenWings,
            ChickenDrumStick,
            ChickenPopcorn
    }
}

Step 3 - Calling the form

Now that we have our form class ready, let's call the form whenever the user starts a conversation. Now there are several ways to do this. We can call or initiate the form within a Dialog or we can directly serve it from the MessageController inside the Post method. For this demo we will keep it simple and call it directly from MessageController.

public async Task < HttpResponseMessage > Post([FromBody] Activity activity)
{
    if (activity.Type == ActivityTypes.Message) {
        await Conversation.SendAsync(activity, () => Chain.From(() => FormDialog.FromForm(OrderDetails.BuildForm)));
    } else {
        HandleSystemMessage(activity);
    }
    var response = Request.CreateResponse(HttpStatusCode.OK);
    return response;
}

In the above code snippet the Post method is the default method that we can see when we scaffold a new Bot Application project in Visual studio. Let us take a look into the part where we have initiated our OrderDetails form into the conversation.

await Conversation.SendAsync(activity, () => Chain.From(() => FormDialog.FromForm(OrderDetails.BuildForm)));

Here we have used the FormDialog.FromForm method to pass our OrderDetails form using OrderDetails.BuildForm to the Dialog Chain.

Step 4 - See this in action

To see the formflow in action we need to launch the application in visual studio. Then in the bot framework emulator enter the address where the web application is running and connect. We can send any simple message to the bot to trigger our form for now.

display the menu items

Confirmation step for order

In the above image we can see how the simple class can create a fully guided conversational application. Beside being fast and manageable and that we have to write very little code, it comes along with packed features that come out of the box.

As for example in the above image, before confirmation instead of “ok”, we could have said “no” and the form would have given us option to change any of our current selection. Or at point in the conversation we could type “status” to see the status of the form and “help” to get help about the options.

To see all other basic features that are available out of the box please visit here.

So this concludes the basics of formflow. In the next part we will look into more advanced features including dynamic formflow and how to display the form options as Hero card in carousel format.