6 Entities

While intents map words and phrases to a specific action, entities add context to the intent itself. They help to describe the intent more fully and enable your bot to complete a user request. The OrderPizza intent, for example, describes a user request, but only in general terms. To fill in the specifics, this intent is augmented by the PizzaSize entity, which identifies values like large, medium, and small from the user input. There are two types of entities, both of which you can declare as variables in the dialog flow: built-in entities that we provide for you and custom entities, which you can add on your own.

Built-In Entities

We provide entities that identify objective information from the user input, like time, date, and addresses.

Description of the illustration system_entities_01.png

These built-in entities are divided into two groups: simple entities that extract primitive values like strings and integers, and complex entities that detect values from the user input using groups of properties.

Whenever you define a variable as an entity in your dialog flow, be sure to match the entity name and letter case exactly. In other words, you’ll get a validation error if you enter confirm: "YESNO" instead of confirm: “YES_NO”.

Simple Entities

Entity Name	Content Identified	Examples
NUMBER	Matches ordinal and cardinal numbers	1st first 1 one
EMAIL	An email address—The NLU system can recognize email addresses that have combinations of letters (a-z), numbers (0–9), underscores (_) and plus (+) and minus (-) signs before the at symbol (@). The address can’t have a dot (.) immediately after the @ symbol, but the domain name (which is comprised of letters and numbers only), must include the dot.	[e-mail]
ADDRESS	An address or location-related entities	200 Oracle Parkway, Redwood Shores, CA
YES_NO	Detects a “yes” or “no”.	Yes, Yeah, no

Complex Entities

Unlike simple entities, complex entities extract content using properties, each of which recognizes a specific value. When you train and test your intents, you can see these properties in the Tester. The JSON output that’s returned by the NLU Engine shows these entities along with the value that they’ve identified from the user input.

Description of the illustration entity_properties.png
When you define a variable in your dialog flow that uses a complex entity, you will need to include these properties in the value expression. See Accessing Variable Values with Apache FreeMarker FTL.

Entity Name	Content Extracted	Examples	Properties (Referenced in Value Expressions)	Example NLU Engine Response
DATE	An absolute or relative date	November 9, 2016 Today	originalString date	{ "date" : 895685400000, "value" : 895685400000, "entityName" : "DATE" }
TIME	A specific time	2:30 pm	hrs mins secs “hourFormat”:”PM”	{ "hrs":8, "mins":0, "secs":0, "hourFormat":"PM", "entityName":"TIME" }
DURATION	The amount of time between the two endpoint of a time interval	4 years two weeks	startDate endDate	{ "startDate":1482019200000, "endDate":1482623999999, "entityName":"DURATION" }
SET	Recurring time periods.	Every Tuesday Every two weeks	minute—The range is {0–59} hour—The range is {0–23} dayOfTheMonth—The range is {1–31} monthOfTheYear—The range is {1–12} dayOfTheWeek—{0–6}, with 0 being Sunday year	{ "minute" : [ 30 ], "hour" : [ 19 ], "dayOfTheMonth" : [ 15 ], "monthOfTheYear" : [ "MARCH" ], "entityName" : "SET" }
CURRENCY	Representations of money	$67 75 dollars	amount currency totalCurrency	{ "amount":50, "currency":"dollar", "total_currency":"50.0 dollar", "entityName":"CURRENCY" }
PHONE NUMBER	A phone number—The NLU Engine recognizes phone numbers that have seven or more digits (it can’t recognize any phone number with fewer digits). All country codes need to be prefixed with a plus sign (+), except for the United States of America ( where the plus sign is optional). The various parts of the phone number (the area code, prefix, and line number), can be separated by dots (.), dashes (-), or spaces. If there are multiple phone numbers entered in the user input, then the NLU Engine can recognize them when they’re separated by commas. It can’t recognize different phone numbers if they’re separated by dots, dashes or spaces.	(650)-555–5555 16505555555 +61.3.5555.5555	phoneNumber completeNumber	{ "phone_number":"(650)-555-5555", "complete_number":"(650)-555-5555", "entityName":"PHONE_NUMBER" }
URL	A URL—This entity can extract IPv4 addresses, Web URLs, deep links (http://example.com/path/page), file paths, and mailto URIs. If the user input specifies login credentials, then it must also include the protocol. Otherwise, the protocol isn’t required.	http://example.com	protocol domain fullPath	{"protocol":"http","domain":"example.com",}

Custom Entities

Because the built-in entities extract generic information, they can be used in a wide variety of bots. Custom entities, on the other hand, have a narrower application. Like the FinancialBot’s AccountType entity that enables various banking transactions by checking the user input for keywords like checking, savings, and credit cards, they’re tailored to the particular actions that your bot performs.

Custom Entity Types

Entity Type	Description
Derived	A derived entity is the child of a built-in entity or another entity that you define. You base this relationship on prepositional phrases (the “to” and “from” in utterances like I want to go from Boston to Dallas or Transfer money from checking to savings).
Value list	An entity based on a list of predetermined values, like menu items or the FinancialBot’s checking, credit, and card options that are output by the System.List component. You can optimize the entity’s ability to extract user input by defining synonyms. These can include abbreviations, slang terms, and common misspellings. Synonym values are not case-sensitive: USA and usa, for example, are considered the same value.
Entity list	A super set of entities. Using a travel bot as an example, you could fold the entities that you’ve already defined that extract values like airport codes, cities, and airport names into a single entity called Destination. By doing so, you would enable your bot to respond to user input that uses airport codes, airport names, and cities interchangeably. So when a user enters “I want to go to from JFK to San Francisco,” the Destination entity detects the departure point using the airport code entities and the destination using the cities entity.
Regular Expression	Resolves an entity using a regular expression (regex). Using regular expressions lets your bot identify pre-defined patterns in user inputs, like ticket numbers.

Create Entities

To create an entity:

1. Click Entities () in the side navbar.
2. Click Add Entity and then enter the name.
3. In the Configuration section, choose entity type from the list.
   
   
   • Value List—Define a set of values for an entity that’s defined by predetermined terms.

     Note:

     Adding punctuation or special characters to the same term creates different values: the entity can't match USA from the user input with either USA? or USA!, or cafe with café. To match a value regardless of case or punctuation, create a regular expression entity. You can define it using syntax like (\w+)
     .
     
     

     Tip:

     You don’t need to add your value list entities one at a time. Like intents, you can define groups of entities in a CSV file first, then import them. You can create this file from scratch, or reuse the entities that you’ve exported from another bot.
   • Entity List—A super set of entities.
   • Derived Entities—A derived entity is the child of another entity (either built-in or custom) that’s modified by a preposition that you add using the Preceding Phrase or Following Phrase rules.
     
     

     Important:

     Derived entities can’t be parent entities. And because the NLU Engine detects derived entities only after it detects all of the other types of entities, you can’t add derived entities as members of an entities list. Only custom or the built-in entities can belong to a list.
   • Regular Expression—Enter the regular expression (regex) pattern. Unlike the other entity types, regex-based entities don’t use NLP because the matching is strictly pattern-based.
     
     For example this expression, (?<=one\s).*(?=\sthree) returns the word that’s between “one” and “three” in the user input.
     
     
4. Next steps:
   1. Add the entity to an intent. This informs the bot of the values that it needs to extract from the user input during the language processing. See Add Entities to Intents.
   2. If needed, add the entity to an Entity List entity or a Derived entity.
   3. In the dialog flow, declare a context variable for the entity, one that references that value that holds the language processing result, nlpresult (for example, iResult: “nlpresult”). See Dialog Flow Syntax.
   4. Reference this context variable in the System.Intent component.
      The System.MatchEntity also extracts entity values.
   5. After the System.Intent component, which processes the input string, access the variable values using Apache FreeMarker expressions. For example, you can use the entityMatches keyword to iterate over entity values (${iResult.value.entityMatches[‘name of entity’]}). See Built-In FreeMarker Array Operations.

Import Value List Entities from a CSV File

Rather than creating your entities one at a time in the Bot Builder, you can create entire sets of them when you import a CSV file containing the entity definitions. The CSV file is divided into three columns: entity, value, and synonyms. For example:

entity,value,synonyms
CheeseType,Mozzarella,Mozarela:Mozzarela
CheeseType,Provolone,	
CheeseType,Gouda,	
CheeseType,Cheddar,
PizzaSize,Large
PizzaSize,Medium
PizzaSize,Small

1. Click Entities () in the side navbar.

2. Click More, choose Import Value list entities, and then select the .csv file from your local system.
   
   

3. Add the entity or entities to an intent (or to an entity list and then to an intent).

Export Value List Entities to a CSV File

You can export your entity definitions in a CSV file for reuse in another bot. To do this:

1. Click Entities () in the side navbar.

2. Click More, choose Export Value list entities and then save the file.
   
   

   The exported .csv file is named for your bot.