Entity Rules

Chances are you might be want to perform additional validations on entity values as entered by the users. While the entity type selected when adding an entity node to a dialog does impose some restrictions, these are not always sufficient. Entity rules are additional processing hints and validations that can be dynamically set in the script for an entity. These rules need to be set before the entity prompt in the dialog flow.

Add a script node at the beginning of the dialog or just before the concerned entity node with the following script:

context.entityRules.<entityName> = {
      "ruleName": "value"
   }

Subentity rules can be part of the composite entity rules:

context.entityRules.<compositeEntityName> = {
    <subentityName> : { 
      "ruleName": "value"
     }
   }

Below are the entity rules that can be included as ruleName in the above script for each entity type.

ruleName	Value	Description
Generic rules
processLatestSentence	true/false	To restrict checking for entity values to the sentences from the current volley alone.
patternsOnly	true/false	To restrict matching to an entity pattern. If no pattern matches then do not look for the entity value anywhere as per the default setting.
allowConfirmation	true/false	The entity value will be presented to the user after each input and will exit the entity only after a confirmation from user. Allows for a list to be iteratively modified. On each show, the entity value is the currently selected items.
confirmYesSynonyms	<concept names>	Additional words/phrases to be used to confirm an entity value. Used in conjunction with allowConfirmation.
confirmNoSynonyms	<concept names>	Additional words/phrases to be used to cancel a confirmation entity. In case of a negative confirmation, the entity value will beset to null Used in conjunction with allowConfirmation.
For String type entity For Description entity type
stripLeading	<concept name>	To remove words in a concept from the start of the extracted string, unless the entity is at the beginning of the sentence. The value can be a single concept name or a space-separated list of concepts or an array of concept names. If the list is an array, then the strings can be a pattern. If that pattern contains the start of the sentence marker as the first character then this pattern will be applied to an extracted value from the start of the sentence.
stripTrailing	<concept name>	To remove words in a concept from the end of the extracted string, unless the entity is at the end of the sentence. The value can be a single concept name or a space-separated list of concepts or an array of concept names. If the list is an array, then the strings can be a pattern. If that pattern contains the end of sentence marker as the last character then this pattern will be applied to an extracted value from the end of the sentence.
avoidSingleVerb	true	If set to true, then any value that is just a verb is ignored, unless it is the entire input.
avoidSingleWord	<concept name>	To ignore any value that is a member of the concept, unless it is the entire input. The value can be a single concept name or a space-separated list of concepts or an array of concept names.
For Currency entity type
defaultCode	<currency code> or <country code>	If no code is mentioned in user input, this value will be picked as code. The value needs to be a 3 letter currency code or two-letter country alpha-2 code.
maxDigits	<number>	To restrict the amount length. If the amount length exceeds the value it will be discarded.
currencyCodes	[<currency code>,<currency code>] or [<country code>,<country code>]	To restrict the codes list. If the user entered code is not in the given list then the value will be discarded.
For PersonName entity type
disablePatterns	An array of person name patterns to ignore	To disable patterns in extracting a person’s name when not applicable in specific scenarios.
ignoreWords	<concept name>	Many names, particularly in English, can be interpreted as a name, particularly if they are capitalized. Words in the concept are not to be considered as names. The concept name could be a space-separated list of concepts or an array of concepts.
For Time entity type
preferredTimes	{ “from” : <from-time>, “to” : <to-time> }	Can be used to default times when they are ambiguous, e.g. “3” will become “3 pm” if the preferredTimes are 9 am to 6 pm. If the time cannot be placed inside the range then it will pick am/pm based on which is closest. If there are two possibilities or equal distance then the “daylight/standard awake” hours will be used. The times should be ISO 8601 format, THH:MM
	{ “from” : [], “to” : []}	Alternatively, the “from” and “to” keys can be arrays with 7 members representing the time for each day, from Sunday to Saturday. Each value should be in the in Thh:MM format or an empty string to indicate there is no preference.
	{ “favor” : <keyword> }	Or if the “favor” keyword is present then that keyword will guide the selection. Valid keywords are “future”, “past”, “am”, “pm”.
timeRangePossible	true/false	If true then the dialog will be looking for two time values in the user input. Influences how “10 to 4” is interpreted. By default, this will be “3:50” but if there is the possibility of a range then will be decoded as 2 times “10:00” and “16:00”
range	{ “from” : <from-date>, “to” : <to-date> }	To extract date-times only in the specified range. Either endpoint is optional. Values can be a date, YYYY-MM-DD, or a DateTime, YYYY-MM-DDTHH:MM:SS (user’s TZ is assumed if none specified) or a keyword: today, tomorrow, yesterday, now. The dates are inclusive.
For Date entity type
range	{ “from” : <from-date>, “to” : <to-date> }	To extract dates only in the specified range. Either endpoint is optional. Values can be a date, YYYY-MM-DD, or a keyword: today, tomorrow, yesterday. The dates are inclusive.
referenceDate	<date>	Sets the reference date to <date>. Values should be a date, YYYY-MM-DD, or a keyword: today, tomorrow, yesterday.
For DateTime entity type
range	{ “from” : <from-date>, “to” : <to-date> }	To extract date-times only in the specified range. Dates and times outside the range will be ignored. Either endpoint is optional. Values should be a date, YYYY-MM-DD, or a DateTime, YYYY-MM-DDTHH:MM:SS (user’s TZ is assumed if none specified) or a keyword: today, tomorrow, yesterday, now. The dates are inclusive.
preferredTimes	{ “from” : <from-time>, “to” : <to-time> }	To set the default times when they are ambiguous, e.g. “3” will become “3 pm” if the preferred hours are 9 am to 6 pm. If the time cannot be placed inside the range then it will pick am/pm based on which is closest. If there are two possibilities or equal distance then the “daylight/standard awake” hours will be used. The times should be ISO 8601 format, THH:MM
	{ “favor” : <keyword> }	Or if the “favor” keyword is present then that keyword will guide the selection. Valid keywords are “future”, “past”, “am”, “pm”.
	{ “from” : [], “to” : []}	Alternatively, the “from” and “to” keys can be arrays with 7 members representing the time for each day, from Sunday to Saturday. Each value should be in the in Thh:MM format or an empty string to indicate there is no preference.
timeRangePossible	true/false	If true then the dialog will be looking for two time values in the user input. Influences how “10 to 4” is interpreted. By default, this will be “3:50” but if there is the possibility of a range then will be decoded as 2 times “10:00” and “16:00”
For DatePeriod entity type
range	{ “from” : <from-date>, “to” : <to-date> }	To extract dates only in the specified range. Either endpoint is optional. Values should be a date, YYYY-MM-DD, or a keyword: today, tomorrow, yesterday. The dates are inclusive.
tense	“past”/”future”	To adjust the date period based on the tense. It does not recalculate the date period, it just adjusts the year.
referenceDate	<date>	To set the reference date to <date>. Values should be a date, YYYY-MM-DD or a keyword: today, tomorrow, yesterday. Any date calculations would be done with reference to this value. For example if the “referenceDate” is set to “2020-01-01” and users says “2 days later” then the entity value would be taken as “2020-01-03”
For ListOfValues entity type
ownership	include/exclude	To look for potential “ownership” phrasing, e.g. “is mine” to determine if a potential choice should be included or excluded from the entity value. Examples of ownership phrases are “is mine”, “belongs to me”, etc.
includeWords	<concept name>	The list of words that indicate this choice is to be included in the entity value and those that don’t reference this list are to be excluded. The words are implicitly checked to see that they are connected to the choice by an auxiliary verb. The value can be an array of strings or a pattern.
excludeWords	<concept name>	The list of words that indicate this choice is to be excluded from the entity value and all the others are included. The words are implicitly checked to see that they are connected to the choice by an auxiliary verb. The value can be an array of strings or a pattern.
For City entity type
ignoreWords	<concept name>	Words in the concept not to be considered as cities. The concept name could be a space-separated list of concepts or an array of concepts or space-separated strings.
For Zipcode entity type
preferredCountries	[<“country1”>,<“country2”>,..]	Tries to identify zip code from the given set of preferredCountries along with the user location country and the gleaned countries from the input. Need to add two-letter country alpha-2 codes in place of <“”country1″”>,<“”country2″”>,..
For Location entity type
preferredCountries	[<“country1”>,<“country2”>,..]	Tries to identify zip code from the given set of preferredCountries along with the user location country and the gleaned countries from the input. Need to add two-letter country alpha-2 codes in place of <“”country1″”>,<“”country2″”>,..
For Number entity type
asString	true	Returns a number as a string, preserving leading zeros