Forms

One of the most common conversation patterns is to collect a few pieces of information from a user in order to do something (book a restaurant, call an API, search a database, etc.). This is also called slot filling.

If you need to collect multiple pieces of information in a row, we recommended that you create a FormAction. This is a single action which contains the logic to loop over the required slots and ask the user for this information. There is a full example using forms in the examples/formbot directory of Rasa Core.

When you define a form, you need to add it to your domain file. If your form’s name is restaurant_form, your domain would look like this:

forms:
  - restaurant_form
actions:
  ...

Configuration File

To use forms, you also need to include the FormPolicy in your policy configuration file. For example:

policies:
  - name: "FormPolicy"

Form Basics

Using a FormAction, you can describe all of the happy paths with a single story. By “happy path”, we mean that whenever you ask a user for some information, they respond with the information you asked for.

If we take the example of the restaurant bot, this single story describes all of the happy paths.

## happy path
* request_restaurant
    - restaurant_form
    - form{"name": "restaurant_form"}
    - form{"name": null}

In this story the user intent is request_restaurant, which is followed by the form action restaurant_form. With form{"name": "restaurant_form"} the form is activated and with form{"name": null} the form is deactivated again. On the “happy path”, where the user is cooperating well and the system understands the user input correctly, the form is filling all requested slots without interruption.

The FormAction will only request slots which haven’t already been set. If a user starts the conversation with I’d like a vegetarian Chinese restaurant for 8 people, then they won’t be asked about the cuisine and num_people slots.

Note that for this story to work, your slots should be unfeaturized. If any of these slots are featurized, your story needs to include slot{} events to show these slots being set. In that case, the easiest way to create valid stories is to use Interactive Learning.

Custom slot mappings

If you do not define slot mappings, slots will be only filled by entities with the same name as the slot that are picked up from the user input. Some slots, like cuisine, can be picked up using a single entity, but a FormAction can also support yes/no questions and free-text input. The slot_mappings method defines how to extract slot values from user responses.

Here’s an example for the restaurant bot:

def slot_mappings(self) -> Dict[Text, Union[Dict, List[Dict]]]:
    """A dictionary to map required slots to
        - an extracted entity
        - intent: value pairs
        - a whole message
        or a list of them, where a first match will be picked"""

return {
        "cuisine": self.from_entity(entity="cuisine", not_intent="chitchat"),
        "num_people": [\
            self.from_entity(\
                entity="number", intent=["inform", "request_restaurant"]\
            ),\
        ],
        "outdoor_seating": [\
            self.from_entity(entity="seating"),\
            self.from_intent(intent="affirm", value=True),\
            self.from_intent(intent="deny", value=False),\
        ],
        "preferences": [\
            self.from_intent(intent="deny", value="no additional preferences"),\
            self.from_text(not_intent="affirm"),\
        ],
        "feedback": [self.from_entity(entity="feedback"), self.from_text()],
    }

Validating user input

After extracting a slot value from user input, the form will try to validate the value of the slot. Note that by default, validation only happens if the form action is executed immediately after user input. This can be changed in the _validate_if_required() function of the FormAction class in Rasa SDK. Any required slots that were filled before the initial activation of a form are validated upon activation as well.

By default, validation only checks if the requested slot was successfully extracted from the slot mappings. If you want to add custom validation, for example to check a value against a database, you can do this by writing a helper validation function with the name validate_{slot-name}.

Here is an example , validate_cuisine(), which checks if the extracted cuisine slot belongs to a list of supported cuisines.

    @staticmethod
    def cuisine_db() -> List[Text]:
        """Database of supported cuisines"""

return [\
            "caribbean",\
            "chinese",\
            "french",\
            "greek",\
            "indian",\
            "italian",\
            "mexican",\
        ]

    def validate_cuisine(
        self,
        value: Text,
        dispatcher: CollectingDispatcher,
        tracker: Tracker,
        domain: Dict[Text, Any],
    ) -> Dict[Text, Any]:
        """Validate cuisine value."""

if value.lower() in self.cuisine_db():
            # validation succeeded, set the value of the "cuisine" slot to value
            return {"cuisine": value}
        else:
            dispatcher.utter_message(template="utter_wrong_cuisine")
            # validation failed, set this slot to None, meaning the
            # user will be asked for the slot again
            return {"cuisine": None}

Handling unhappy paths

Of course your users will not always respond with the information you ask of them. Typically, users will ask questions, make chitchat, change their mind, or otherwise stray from the happy path. The way this works with forms is that a form will raise an ActionExecutionRejection if the user didn’t provide the requested information. You need to handle events that might cause ActionExecutionRejection errors in your stories. For example, if you expect your users to chitchat with your bot, you could add a story like this:

## chitchat
* request_restaurant
    - restaurant_form
    - form{"name": "restaurant_form"}
* chitchat
    - utter_chitchat
    - restaurant_form
    - form{"name": null}

In some situations, users may change their mind in the middle of form action and decide not to go forward with their initial request. In cases like this, the assistant should stop asking for the requested slots. You can handle such situations gracefully using a default action action_deactivate_form which will deactivate the form and reset the requested slot.