# Task Requirements

Task requirements specify a piece of information that the user must provide before Answer Server can complete the task. Tasks can have multiple requirements.

When a user provides information to satisfy a requirement, Answer Server updates a variable. It stores the variable to use later in the task (for example to send information to an external system). By default, Answer Server stores the variable only for the duration of the current task. You can also choose to store a variable for the whole conversation session.

To configure requirements, you set the `requirements` property in the configuration object for an individual task. The requirements property takes an array of requirement objects. The following table describes the properties that you use to define a requirement.

Property | Type | Description
--- | --- | ---
`id` | string | (Required) A unique ID for the requirement. Answer Server uses this value as the name of the task or session variable that it stores for this requirement.
`prompt` | string | (Required) The prompt to send to the user to request the information. You can include session and task variables, by inserting the variable ID in double curly brackets, for example `{{MYVARIABLE}}`. The variable must already be set in an earlier part of the task (for a task variable) or conversation session (for a session variable). You can optionally use the `task:` or `session:` prefix to specify the type of variable, for example `{{task:MYVARIABLE}}`. If you do not use a prefix, Answer Server searches for the variable in the task variables first, and then the session variables.
`scope` | enum, string | (Optional) The scope of the variable: `local` or `session`. The default value is `local`, which means that the variable is available only in the current instance of the current task. Set scope to `session` to store the variable for the whole conversation session.
`validation` | array, strings | (Optional) A list of validators to use to validate the user input. Specify the ID of each validator that you want to use to validate the current requirement. You define the validators separately in the `validators` section of the task configuration JSON file. See Response Validation.
`prompt_required` | Boolean | (Optional) Set to true to require that the prompt for this requirement must be sent to the user before this requirement can be set. By default, Answer Server attempts to answer requirements from the trigger or subsequent user text, unless the requirement does not have any validators (in which case, Answer Server always presents the prompt, and the prompt for the next requirement). For more details, see Automatic Requirement Gathering.
`ask_options` | object | (Optional) Options to use for the `Ask` action when the user text does not pass the requirement validators. By default, if the user text is not valid, the conversation system returns a default message. You can set `ask_options` if you want to treat user text that is not a valid answer for the requirement as a question to ask in your other answer systems. The `ask_options` JSON object can contain the following properties: `max_results` (number) Required. The maximum number of results to retrieve from the other answer systems. `systems` (array, strings) Optional. The systems that you want to send the `Ask` action to.
`suggestions` | array, strings | (Optional) A list of suggested answers to return to the user with the requirement prompt. When you set this option, Answer Server returns the suggestions with the prompt in the `Converse` action response. You can use these values to present suggestions to your users. Answer Server does not validate the configured suggestions. However, it does validate the user responses that include them, so Micro Focus strongly recommends that you use valid values as suggestions. You can include session and task variables, by inserting the variable ID in double curly brackets, for example `{{MYVARIABLE}}`. The variable must already be set in an earlier part of the task (for a task variable) or conversation session (for a session variable). You can optionally use the `task:` or `session:` prefix to specify the type of variable, for example `{{task:MYVARIABLE}}`. If you do not use a prefix, Answer Server searches for the variable in the task variables first, and then the session variables.
`user_cancel` | object | (Optional) An object that defines keywords that a user can use to cancel a task, and the action to perform if they do. For details of the configuration properties, see User Cancellation. The `user_cancel` options in the requirements section override any values that you set in the main task configuration or for the individual task.
`system_cancel` | object | (Optional) An object that defines what actions to take when the requirement receives multiple non-valid responses. For details of the configuration properties, see System Cancellation. The `system_cancel` options in the requirements section override any values that you set in the main task configuration or for the individual task.

When Answer Server runs a task that has requirements, it returns the `pre` response for the task (if present), and then the prompt for the first requirement. Each prompt returns in a separate `<prompt>` tag in the same `Converse` action response, and you can choose how to display this information in your user interface.

For example:

    {
       "initial_task" : "GREET",
       "tasks" : [
          {
             "id" : "GREET",
             "pre" : {
                "response" : "Hello and welcome to the Virtual Assistant. Before we get started, I'd like to ask you a couple of questions."
             },
             "requirements": [
                {
                   "id": "USER_NAME",
                   "prompt": "What is your name?",
                   "prompt_required": true,
                   "scope": "session"
                },
                {
                   "id": "USER_COUNTRY",
                   "prompt": "What country do you live in?",
                   "prompt_required": true,
                   "validation": [ "VALIDATE_COUNTRIES" ]
                }
             ]
          }
       ],
       "validators": [
          {
             "id": "VALIDATE_COUNTRIES",
             "eduction": {
                "grammars": "place_countries.ecr"
             }
          }
       ]
    }

When the task runs at the start of a conversation session, the user receives the following initial message:

Hello and welcome to the Virtual Assistant. Before we get started, I'd like to ask you a couple of questions.
What is your name?

When the user answers, the task stores the answer in the `USER_NAME` session variable and then returns the following message:

What country do you live in?

Answer Server validates the user input by using the `VALIDATE_COUNTRIES` validator. For more information about validator configuration, see Response Validation. If the response is valid, Answer Server stores the value in the `USER_COUNTRY` task variable.

## Automatic Requirement Gathering

The example in the previous section uses the `prompt_required` flag to ensure that Answer Server sends the prompt to the user, and the user must provide an answer to each requirement individually.

In many cases, you might want to automatically check the user response text for additional answers to your task requirements. For example, if you send a prompt to a user for their name, and they reply with their name and company, you might want to extract the company name from this text, rather than subsequently asking the user what company they work for.

Automatic requirement gathering applies only to requirements that have validators, and where the prompt is not required. When a user sends some text, Answer Server checks whether any portion of their input text matches the validator for the current requirement. If it does, it also checks whether the user input text matches the validators for any other requirements in the current tasks, and sets the appropriate task and session variables if it does.

NOTE: For requirements that do not have validators (for example, those with free text input), Answer Server always presents the prompt. It also always presents the prompt for the following requirement, even if the user provided the information in an earlier response.

This process applies to the initial user text that triggers the task. If the trigger text contains the answer for the first requirement in the task, Answer Server also checks whether the text contains answers for other requirements.

For example:

    {
       "tasks" : [
          {
             "id" : "LUNCH",
             "pre" : {
                "response" : "I can help you order some lunch."
             },
             "trigger" : {
                "regex" : {
                   "pattern" : "(Book|order) .* lunch"
                }
             },
             "requirements": [
                {
                   "id": "FOOD_TYPE",
                   "prompt": "Do you feel like a sandwich or a panini?",
                   "validation": [ "FOODTYPEVALIDATOR" ]
                },
                {
                   "id": "FILLING",
                   "prompt": "What filling would you like?",
                   "validation": [ "FILLINGVALIDATOR" ],
                   "suggestions": ["cheese", "ham", "turkey"]
                }
             ],
             "post" : {
                "response" : "We'll get you a {{FILLING}} {{FOOD_TYPE}} right away!"
             }
          }
       ],
       "validators" : [
          {
             "id" : "FOODTYPEVALIDATOR",
             "simple" : {
                "matches": [
                   { "values": [ "sandwich", "panini" ] }
                ]
             }
          },
          {
             "id" : "FILLINGVALIDATOR",
             "simple" : {
                "matches": [
                   { "values": [ "cheese", "ham", "turkey" ] }
                ]
             }
          }
       ]
    }

If a user triggers this task with the text I want to order some lunch, Answer Server returns the prompt for the first requirement as usual. However, if the user triggers the task with the text I want to order a cheese panini for lunch, the trigger text provides the answer to both of the requirements. In this case, Answer Server responds with the initial task prompt (I can help you order some lunch), and the acknowledgment (We'll get you a cheese panini right away).

Related Topics

- Post-Task Actions
- Response Validation
- Conversation Triggers

_FT_HTML5_bannerTitle.htm