Add intents and entities to your model

To begin, you will want to build up the basic structure of your model by defining:

  • Intents
  • Entities
  • The relationships between intents and entities

Intents

An intent is something a user might want to do in your application. You might think of intents as actions (verbs); for example, to order. For more information about intents, see Intents.

Add intents

To add intents to your model:

  1. In Mix.nlu, click the Develop tab.

  2. On the Intents bar, click in the Search and Add text field. Type a name for the new intent (for example, ORDER_COFFEE). Click the Add an Intent icon Add entity icon.

    Add new intent

The intent name is added to the list of intents.

Edit an intent name

To edit an intent name:

  1. In the Develop tab intents list, open the menu for the intent.
  2. Select Edit intent name. You can now edit the text of the intent name
  3. Make the edits to the intent name.
  4. Press Enter or click the check icon to make the change. If you instead want to cancel the edit and go back to the existing name, press Escape or click the x icon.

Entities

Entities collect additional important information related to your intent. You might think of entities as analogous to variable slots or parameters that, when filled in with user-provided details, make the intent specific and actionable.

For example, if a user has the intent to order an coffee-based drink, the user would need to specify to the agent what type of coffee they want, how big a cup they want, any flavoring they want to add, and so on. These details can vary from order to order, but generally speaking some of these details will always need to be specified to make a coffee order. So in this case for example you might include entities such as COFFEE_TYPE, COFFEE_SIZE, FLAVOR, and so on.

Each entity, as a variable, can take on some set of possible values. So for example, when a user wants to order a coffee and says “Can I have a large vanilla latte,” entities take on the following values:

  • COFFEE_TYPE takes the value “latte”
  • COFFEE_SIZE takes the value “large”
  • FLAVOR takes the value “vanilla”

Custom and predefined entities

This section describes how to create custom entities, which are the entities that are specific to your Intent. You can also use one of the existing predefined entities, which are entities that have already been defined to save you the trouble of creating them from scratch.

Examples of predefined entities include:

  • Monetary amounts
  • Boolean values
  • Calendar items (dates, times, or both)
  • Cardinal and ordinal numbers

For more information, see Predefined entities.

To simplify your model, avoid adding a unique entity for each instance of a similar item. Instead, add a single entity that describes a general type of item. For example, instead of defining entities for Cappuccino, Espresso, and Americano, define a single entity named COFFEE_TYPE.

Data types

An entity is like a variable containing a piece of information relevant to an intent. Like a variable in a computer program, an entity in Mix can be specified with a data type aligned with the kind of contents the entity will hold. Entities in Mix are shared between Mix.nlu and Mix.dialog. The data type forms a contract between Mix.nlu and Mix.dialog that allows dialog designers to use methods and formatting appropriate to the data type of the entity in messages and conditions.

The available data types are as follows:

Data types
Data type Description Use case examples
Generic Text data without any special format. A name of a person, names of product types
Yes/No Yes or no The answer to a yes/no question
Boolean True or false The answer to a true/false question
Number A numerical quantity A quantity measured with a whole number or decimal
Digits A sequence of digits from 0-9 A PIN, an ID code
Alphanumeric A sequence of letters or numbers, A-Z, a-z, 0-9 A user name, an ID code, a license plate number
Date A YYYYMMDD date A calendar date
Time An HHMM time A clock time
Amount A quantity with units, defined by the magnitude and units A monetary amount
Distance A measure of distance, including magnitude and distance unit Distance in kilometers, meters, miles, and so on
Temperature A measure of temperature, including possibly signed magnitude and units Temperature in Celsius or Fahrenheit

If you have a previously existing project, with previously created entities, by default the entities will initially have a special data type of “Not set.” This will behave the same as Generic type. You cannot set a newly created entity to Not set.

Collection methods

An entity also has a collection method. A collection method is related to how the set of possible values of the entity can be enumerated or defined.

  • Can the possible values be conveniently enumerated in a list?
  • Are the possible values strings of characters following a simple pattern you can describe with a regular expression?
  • Can the possible values be expressed as some sort of grammar with rules defining what is a valid value?
  • Can the possible values be expressed as a subtype or composition of other entities?
  • Or can the entity contain any open-ended text or spoken input that might be provided?

Along these lines, entity collection methods are as follows:

Collection methods
Collection method Description
List A list entity has possible values that can be enumerated in a list. For example, if you have defined an intent called ORDER_COFFEE, the entity COFFEE_TYPE would have a list of the types of drinks that can be ordered. See List entities.
Regex-based A regex-based entity defines a set of possible structured text string values using a regular expression pattern. See Regex-based. For example account numbers, postal (zip) codes, order numbers, and other pattern-based formats.
Rule-based A custom rule-based entity defines a set of values based on a GrXML grammar file. While regular expressions can be useful for matching patterns in text-based input, grammars are useful for matching multi-word patterns in spoken user inputs. This type is only available for some users. See Rule-based entities.
Relationship A relationship entity has a specific relationship to one or more existing entities, with either a subtype (isA) or composition (hasA) relationship. See Relationship entities. For example a NAME hasA FIRST_NAME and hasA LAST_NAME; a DESTINATION isA LOCATION
Freeform A freeform entity is used to capture user input that you cannot enumerate in a list. For example, a text message body could be any sequence of words of any length. In the query “send a message to Adam hey I’m going to be ten minutes late”, the phrase “hey I’m going to be ten minutes late” becomes associated with the freeform entity MESSAGE_BODY. See Freeform entities.

Data type and collection method compatibility

Specific data types are compatible with some collection methods but not with others. Each data type has a default collection method which will be set initially if a data type is selected but the collection method is not specified.

Data type and collection method compatibility
Data type Compatible collection methods Default collection method
Generic All collection methods List
Yes/No List
Rule-based
Relationship isA YES_NO
Relationship isA YES_NO
Boolean List
Rule-based
Relationship isA nuance_BOOLEAN
Relationship isA nuance_BOOLEAN
Number Rule-based
Regex
Relationship isA nuance_CARDINAL_NUMBER
Relationship isA nuance_DOUBLE
Relationship isA nuance_NUMBER
Relationship isA nuance_NUMBER
Digits Rule-based
Regex
Relationship isA nuance_CARDINAL_NUMBER
Relationship isA nuance_CARDINAL_NUMBER
Alphanumeric List
Rule-based
Regex
List
Date Rule-based
Relationship isA DATE
Relationship isA DATE
Time Rule-based
Relationship isA TIME
Relationship isA TIME
Amount Rule-based
Relationship isA nuance_AMOUNT
Relationship isA nuance_AMOUNT
Distance Rule-based
Relationship isA nuance_DISTANCE
Relationship isA nuance_DISTANCE
Temperature Rule-based
Relationship isA nuance_TEMPERATURE
Relationship isA nuance_TEMPERATURE

When creating a new entity, Mix will support you in selecting a compatible collection method. When you first create your entity, Mix will automatically assign the default compatible collection method.

If you then decide to choose a different collection method, Mix will give you recommendations for the most compatible collection methods and advise you on which collection methods are not recommended for the data type.

If you use Relationship isA as a collection method, the predefined entities available to choose from for the isA relationship will be restricted based on what is compatible with the chosen data type. For example, if your data type is Date, Mix will allow you to choose Relationship isA DATE.

The Generic data type should be used if you want to set an entity with collection method of isA relationship to predefined entities that are not covered by other data types. For example, nuance_DURATION or nuance_QUANTITY.

Why is compatibility important?

Choosing collection methods compatible with the data type helps Dialog work more effectively when Dialog is using the NLU service for interpretation of the text of user inputs. In this case NLU is more likely to capture entity values whose format aligns with the format of the data type Dialog expects. This allows you to more effectively tune conditions and message formatting in your dialog flows.

Impacts of changes to data or collection method

If you try to change either the data type or the collection method in a way that would break compatibility, you will receive a warning, and be invited to select a collection method compatible with your data type.

Data type and collection method compatibility

You can however choose to ignore the compatibility warning and proceed.

Create an entity

To add entities to your model:

  1. On the Entities bar, click in the Search and Add text field. Type the name of the entity (for example, COFFEE_TYPE). Click the plus (+) icon to start creating the new entity. A menu Add a new entity to collect appears.
  1. Under Add a new entity to collect, select a data type for your entity.

    Select data type

  2. Click the Add an Entity icon Add entity icon to create the new entity.

  3. Click the name of the new entity in the Custom Entities list to open the entity editor and perform additional configurations.
    The entity editor appears. It contains two sections: Data type and Advanced settings. The Data type section is collapsed initially, but allows you to modify the data type. The Advanced settings section allows you to set other configurable items for the entity.

    Advanced settings

  4. To simplify things for you, the default collection method for your chosen data type is preselected for you. If you are happy with this, and the default is not the list collection method, you are done. Otherwise, continue. If the default collection method chosen is list, proceed to step 8. Otherwise click the Edit collection method toggle and then proceed.

    Edit collection method

  5. Under How you are collecting from the user, select a collection method for the entity.
    Mix gives you a short list of recommended collection methods for your chosen data type. Again, the most recommended default option for your data type is pre-selected.

    Choose collection method

  6. Make sure to select the sensitive checkbox if your entity will collect sensitive data that should not appear in call logs.

    Sensitive checkbox

  7. Configure other details of the entity as appropriate (see the Advanced settings table below for a description of the fields).

    Advanced settings

Advanced settings

The following settings are available in the advanced settings section. Note that some of these are applicable only when specific collection methods are selected.

Advanced settings
Field Description
Collection method Specifies the type of entity. Selectable under How you are collecting info from the user .
Referenced as Defines how the entity can be referred to; for example, whether it is referring to a person (CONTACT: “him”), a place (CITY: “there”), a thing (APPOINTMENT, “it”), or a moment in time (APPOINTMENT_TIME: “then”). These are used for handling anaphoras in dialogs.
Sensitive Indicates whether the entity will collect sensitive personally identifiable information. Values assigned to any entity marked as Sensitive at runtime will be redacted in call logs. For more details, see Handling sensitive information
Note: This only applies to call logs, not diagnostic logs.
Dynamic (Appears when editing entities with list collection method only) Indicates if the entity is dynamic or not. Dynamic list entities allow you to upload data dynamically at runtime. See Dynamic list entities.
Literals (Appears when editing entities with list collection method only) Lets you enter literals and values. A set of literals is the range of tokens in a user’s query that corresponds to a certain entity. With literals, you can specify misspellings and synonyms for an entity’s value. For example, in the queries “I’d like a large t-shirt” and “I’d like t-shirt, size L”, the literals corresponding to the entity SHIRT_SIZE are “large” and “L”, respectively. In both cases, the value is the same. Literals can be paired with values, which are then returned in the NLU interpretation result. For example, “small”, “medium”, and “large” can be paired with the values “S”, “M”, and “L”. For projects that include multiple languages, you can specify variations per language/locale for an entity value.
See List entities for details.
Note: There is a limit to the number of literals that you can enter.
Your relationships (Appears when editing entities with relationship collection method only) Lets you define the entity in relation to other user-defined or predefined entities.

Manage entities

The Entities area provides some additional tools for managing entities.

Manage entities

Upload entity literals

An Upload a File action is available on the Entities bar. This lets you upload values, or value-literal pairs for a list collection method entity via either a LIST or NMLIST file respectively. For more details on the format of these files, see Import entity literals.

Search for an entity

A search field allows you to search by name for an entity. This can be useful if you have a lot of entities, and you are trying to find a specific one in the list without scrolling.

Filter by data type or collection method

Finally, a filter allows you to display only entities of one data type or collection method.

The next step in developing your model is to link your entities to your intents so that they can be interpreted.

For example, if you have an intent called ORDER_COFFEE that uses the COFFEE_SIZE and COFFEE_TYPE entities, you need to link these entities with the ORDER_COFFEE intent. You also need to link any predefined entities that you want to use.

To link entities to your intents:

  1. On the Intents bar, select the intent.
  2. Click the link entity plus (+) icon and select the entity to link.
  3. Repeat for each entity that you want to link to the intent.