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:
- Simple. Validate against a simple list of words and phrases, which the user input must match exactly.
- Regular expression. Validate against a regular expression pattern, which the user input must match.
- Eduction. Validate against a set of Eduction grammars and entities. This validator uses the embedded Answer Server Eduction module.
- Lua. Validate by using a Lua function. This validator calls a function in an external Lua script, which you must configure in the task configuration file. See Lua Processing Scripts.
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:
|
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. |
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.