Response Validation

Response validation allows you to check that the user response contains the information you need to complete a task, or route to an appropriate task. You use validators in the requirements for your tasks (see Task Requirements).

You can use several different types of validation:

You configure validators in the validators section of the task configuration file. This property takes an array of validators. Each validator must contain a unique ID, and a configuration object (one of simple, regex, eduction, and lua, depending on the validation type). The following sections describe each type of validator configuration in more detail, and provide examples of each type of validator.

Each validator object can also optionally include the properties in the following table.

Property Type Description
invalid_input_lua string (Optional) A Lua function in the configured Lua script to call if the user input is not valid. For example, you might use this to submit the user response to your other answer systems. See Lua Processing Scripts.
inverted Boolean (Optional) Set to true if you want to invert the match (that is, to consider user input text as valid if it does not match the validator). The default value is false (user input text must match the validator).

Simple Validation

In simple validation, you provide a simple list of values that the user input must match.

The following table describes the properties that you can set in the simple validation configuration object.

Property Type Description
matches array, objects

One or more match JSON objects, which contain the following properties:

  • values (array, strings) Required. A list of values that you want to accept as user input for this validator. Answer Server accepts these values if they appear as part of a sentence in the input.
  • return_value (string) Optional. The value that the validator uses if the user input matches any of the values in the array. If you do not set this value, the validator returns the value that was matched in the user input.
case_insensitive Boolean (Optional) Set to true if you want to match values case insensitively. The default value is false (case sensitive matching).

For example:

{
   "tasks": [
      ...
   ]
   "validators": [
      {
         "id" : "UKcountryname",
         "simple" : {
            "matches": [
               {
                  "values": [ "United Kingdom", "UK", "Great Britain", "GB" ],
                  "return_value": "UK" 
               },
               {
                  "values": [ "England", "Northern Ireland", "Scotland", "Wales" ] 
               }
            ],
            "case_insensitive" : true
         }
      }
   ]
}       

This example validator checks that the user input matches one of the listed names for the United Kingdom. If the user text includes one of United Kingdom, UK, Great Britain, or GB, the validator returns the value UK to the task. If the user text includes England, Northern Ireland, Scotland, or Wales, the validator returns the value that the user matches.

Regular Expression Validator

In regular expression validation, you provide a regular expression pattern that the user input string must match.

The following table describes the properties that you can set in the regex validation configuration object.

Property Type Description
pattern string

(Required) A regular expression pattern in ECMAScript regular expression format. The user input text must match the pattern to be valid.
The validator supports named captures, which must have the name <return>. The validator returns the matched value if the input is valid.

case_insensitive Boolean (Optional) Set to true if you want to match values case insensitively. The default value is false (case sensitive matching).

For example:

{
   "tasks": [
      ...
   ]
   "validators": [
      {
         "id": "PRODUCT_CODE",
         "regex": {
            "pattern": "PCO-.*"
         }
      }
   ]
}

This validator matches any string that starts with the value PCO-..

Eduction Validator

In Eduction validation, you specify one or more Eduction grammars (and optionally entities) that the user input string must match. This option uses the Answer Server embedded Eduction module.

The following table describes the properties that you can set in the eduction validation configuration object.

Property Type Description
grammars string

(Required) A comma-separated list of grammars to use to validate the input. You can use Wildcards in the grammar name to specify multiple grammars. However, you cannot use Wildcard values in the directory name. You can specify grammar files with an absolute path or a path relative to the Answer Server working directory.

entities string (Optional) A comma-separated list of entities in the configured grammars to use to validate the input. You can use Wildcards in the entity string to specify multiple entities.

For example:

{
   "tasks": [
      ...
   ]
   "validators": [
      {
         "id": "UK_PHONE",
         "eduction": {
            "grammars": "configuration/number_phone_gb.xml",
            "entities": "phone/all/gb"
         }
      }
   ]
}

This validator checks that the user input text contains a phone number that matches one of the types in the phone/all/gb entity of the number_phone_gb.xml grammar. If the user input text contains a valid match, the validator returns the normalized match text to the task.

Lua Validator

In Lua validation, you specify the name of a Lua function to use to validate the user input.

The function that you specify must accept a string (the text to validate) as the first parameter. You can optionally also use a taskUtils object as the second parameter, if you want to use taskUtils methods in your validator.

When the text is a valid response, the function must a string (the normalized value to use from the user input text). When the user text is not a valid response the function must either return nil or not return a value.

The following table describes the properties that you can set in the lua validation JSON configuration object.

Property Type Description
function string

(Required) The name of the function to call. This function must exist in the Lua script that you configure in your task configuration JSON file (see Lua Processing Scripts).

For example:

{
   "tasks": [
      ...
   ]
   "validators": [
      {
         "id": "FTSE_SYMBOL",
         "lua": {
           "function": "check_ftse_symbol"
         }
      }
   ]
}

This validator calls the check_ftse_symbol function in the task Lua script to validate user input text. If the user input text is valid, the validator sends the value that the function returns to the task.

Process Non-Valid Input

You can configure your response validators to call a Lua function when the user input text fails to validate.

To configure a Lua function, you set the invalid_input_lua property in your validator configuration to the name of the Lua function to call. This function must exist in the Lua script that you configure in your task configuration JSON file (see Lua Processing Scripts).

You can use this function to process non-valid input further. For example, if a user asks a question instead of providing a direct answer to a requirement, you might use the invalid_input_lua function to send the user input text to the Ask action, and retrieve answers from your answer systems.

The function that you specify must take a taskUtils object. If the function sets a response, Answer Server returns this response to the user.

If the function does not update the response, Answer Server uses a default message I'm sorry. I didn't understand that., and then repeats the requirement prompt. You can modify this message, if required (see Default Messages).

For example:

{
   "tasks": [
      {
         "id" : "HOLIDAY",
         "trigger" : {
            "regex" : {
               "pattern" : "(book|go) .* holiday"
            }
         },
         "requirements": [
            {
               "id": "HOLIDAY_LOCATION",
               "prompt": "What country would you like to visit?",
               "validators": [ "COUNTRYVALIDATOR" ] 
            }
         ]
      }
   ],
   "validators": [
      {
         "id": "COUNTRYVALIDATOR",
         "eduction": {
            "grammars": "configuration/place_countries.ecr"
         },
         "invalid_input_lua": "holiday_planner"
      }
   ]
}

If holiday_planner is a Lua function that uses the user input text to send an Ask action, and returns the answer as a prompt, you might get a conversation similar to the following (user text is in italic, Answer Server response in bold):

I'd like to go on holiday.

What country would you like to visit?

What country is Budapest in?

Hungary. What country would you like to visit?

Hungary.


_HP_HTML5_bannerTitle.htm