diff --git a/changelog/11724.doc.md b/changelog/11724.doc.md new file mode 100644 index 000000000000..227717f7e1bc --- /dev/null +++ b/changelog/11724.doc.md @@ -0,0 +1 @@ +Update migration guide and form docs with prescriptive recommendation on how to implement dynamic forms with custom slot mappings. diff --git a/docs/docs/forms.mdx b/docs/docs/forms.mdx index 5a770e762717..c82506e792b7 100644 --- a/docs/docs/forms.mdx +++ b/docs/docs/forms.mdx @@ -300,8 +300,9 @@ If you're using the Rasa SDK we recommend you to extend the provided `FormValidationAction`. When using the `FormValidationAction`, three steps are required to extract customs slots: -1. Define a method `extract_` for every slot that should be mapped in a - custom way. +1. Define a method `extract_` for every slot that should be mapped in a custom way. + Each slot which has been defined in the `domain.yml` file with a custom mapping **must** have its own independent + implementation of an `extract_` method. 2. In your domain file, for your form's `required_slots`, list all required slots, with both predefined and custom mappings. In addition, you can override the `required_slots` method to add dynamically requested slots: you can read more in the @@ -346,18 +347,18 @@ first slot specified in `required_slots` which is not filled. ### Dynamic Form Behavior -By default Rasa will ask for the next empty slot from the slots +By default, Rasa will ask for the next empty slot from the slots listed for your form in the domain file. If you use [custom slot mappings](forms.mdx#custom-slot-mappings) and the `FormValidationAction`, it will ask for the first empty slot returned by the `required_slots` method. If all slots in `required_slots` are filled the form will be deactivated. -If needed, you can update the required slots of your form dynamically. -This is, for example, useful when you need further details based on how -a previous slot was filled or you want to change the order in which slots are requested. +You can update the required slots of your form dynamically. +This is, for example, useful when you need to fill additional slots based on how +a previous slot was filled or when you want to change the order in which slots are requested. -If you are using the Rasa SDK, we recommend you to use the `FormValidationAction` and -override `required_slots` to fit your dynamic behavior. You should implement +If you are using the Rasa SDK, we strongly recommend that you use the `FormValidationAction` and +override `required_slots` to fit your dynamic behavior. You must implement a method `extract_` for every slot which doesn't use a predefined mapping, as described in [Custom Slot Mappings](forms.mdx#custom-slot-mappings). The example below will ask the user if they want to sit in diff --git a/docs/docs/migration-guide.mdx b/docs/docs/migration-guide.mdx index 8e31ba118d65..d79bc11c9928 100644 --- a/docs/docs/migration-guide.mdx +++ b/docs/docs/migration-guide.mdx @@ -1443,9 +1443,20 @@ the mappings will be applied on each user turn regardless of whether a form is a requested_slot: outdoor_seating ``` +#### Rasa-SDK Modifications + If you have used `FormValidationAction` to define custom extraction and validation code in which you override the `required_slots` method, note that `slots_mapped_in_domain` argument has been replaced by the `domain_slots` argument. -You will need to make this replacement to continue using your custom code. +You must make this replacement to continue using your custom code. + +If you have been dynamically filling slots not present in the form's `required_slots` defined in the `domain.yml` +file, note that this behaviour is no longer supported in 3.x. Any dynamic slots with custom mappings, which are set in +the last user turn, will be filled **only if** they are returned by the `required_slots` method of the custom action +inheriting from `FormValidationAction`. To maintain the 2.x behaviour, you must now override the `required_slots` method +of this custom action as per the strong recommendation listed in the [dynamic form documentation](./forms.mdx#dynamic-form-behavior). + +To extract custom slots that are not defined in any form's `required_slots`, you should now use a global [custom slot mapping](./domain.mdx#custom-slot-mappings) +and extend the [ValidationAction class](./action-server/validation-action.mdx#validationaction-class). :::note If you have custom validation actions extending `FormValidationAction` which override `required_slots` method, you should