Entity details

Entity data types

Self-hosted environments: This feature requires engine pack 2.3 (or later) for Speech Suite deployments; engine pack 3.11 (or later) for self-hosted Mix deployments.

Nuance-hosted environments: For entities that were created with an earlier version of Mix.dialog or Mix.nlu, the data type will remain undefined (not set), until you specify it.

Just like variables, entities have a data type. It’s important to choose the data type carefully when you create an entity, since this determines formatting options for dynamic messages using the entity, and methods that can be used in conditions that are based on this entity. Entity data types include: generic, alphanumeric, amount, Boolean, date, digits, distance, number, temperature, and time. See Data types, in the Mix.nlu documentation, for more information.

Entity collection methods

When you choose the data type for an entity, this automatically sets a collection method (also known as entity type), which determines the recognition and interpretation services to be invoked at runtime. Collection methods include: list, relationship, freeform, regex-based, and rule-based.

Using the default collection method for your entities allows you to start developing your dialog design quickly. Later on, perhaps after consulting with a speech science specialist, you might opt for a different collection method for some entities (see Data type and collection method compatibility, in the Mix.nlu documentation, for more information).

Predefined entities in Mix.dialog

Mix.nlu shares with Mix.dialog a set of predefined entities from data packs installed with your Mix platform. Mix.dialog supports these:

• nuance_AMOUNT
• nuance_BOOLEAN
• nuance_CARDINAL_NUMBER
• nuance_DISTANCE
• nuance_DOUBLE
• nuance_EXPIRY_DATE
• nuance_GENERIC_ORDER
• nuance_NUMBER
• nuance_ORDINAL_NUMBER
• nuance_TEMPERATURE

In addition to the entities from the data packs, Mix also provides a set of dialog-specific predefined entities. Mix.dialog supports these:

• DATE
• TIME
• YES_NO

Mix.dialog does not directly support predefined entities. To use any predefined entity in Mix.dialog, you must define a custom entity with an isA relationship to the desired predefined entity. For example, to collect yes/no answers, add a custom entity myYES_NO and define it as a relationship entity of type isA to the predefined YES_NO entity.

Mix.dialog does not support the nuance_CALENDARX predefined entity. If you would like to let users provide either a date or a time, as a single conversation turn, use separate DATE and TIME entities. Set up your design so that once one of them has been collected the other one is not required, either by configuring a question router node for optional entity collection, or by using conditions.

Mix.dialog also does not support these predefined entities: nuance_DURATION, nuance_DURATION_RANGE, nuance_QUANTITY, and nuance_GLOBAL.

Entity attributes

Entities have these attributes:

Entity lifecycle considerations

For text input, the .formattedLiteral attribute of an entity is always identical to the .literal attribute. Since the Try mode only supports text input, .formattedLiteral is not relevant in preview.

You cannot change the .literal or .formattedLiteral attributes of an entity (except by clearing the entity).

By default, a question router node automatically sets .isCompleted to true, for entities it handles, whenever a question and answer node returns with a collected value (and the value has been confirmed if necessary). You can enable Manual complete for an entity, in the question router node that handles it, if your dialog design requires this attribute to be set manually—for example, if the dialog flow must go through additional logic to determine whether the entity can be considered completed, before returning to the question router node. A use case could be a banking app where, after the user said Transfer 500 dollars from my savings account to my checking account, your application makes a backend call to verify whether the savings account’s balance is sufficient. If it is, your application manually sets .isCompleted to true for the entity that stores the amount, and returns to the question router node; otherwise, the application would notify the user and ask if they would like to transfer a different amount.

Only enable Manual complete for entities that the question router node should never automatically mark as completed. In applications involving interdependent entities whose value can sometimes be inferred from one another, it is always possible to set .isCompleted to true for an entity manually. For example, when a bill payment app asks the user how much of their current balance they would like to pay, if the user replies All of it, the app can assign the current balance to the entity that represents the payment amount, and set this entity’s .isCompleted attribute to true. When the user replies with a specific amount, the question router node will still be able to set the entity’s .isCompleted attribute automatically.

Clearing an entity sets its .value, .literal, and .formattedLiteral attributes to NULL, .isRequired to true, .isConfirmed and .isCompleted to false.

At runtime, when the recognition results include an entity, this also sets the .isRequired attribute for this entity to true. The question router node uses this information to determine whether to invoke the question and answer node responsible for this entity to perform any remaining validation, confirmation, and action logic.

If your dialog design requires setting entity attributes manually, choose carefully where you set the corresponding assign actions. For example, if you have a purpose for setting .isRequired to false manually for an entity, the assignment would need to be made just upstream from the question router node that handles this entity in your dialog flow—after the assignment that clears this entity, if any.

For most purposes, the best practice to manage optional entity collection is to use the question router’s Skip input options. Also consider configuring command overrides to extend the focus of question and answer nodes.

List entities

The default collection method for custom generic entities, List, represents a list of possible values.

For list entities, literals and values are language-specific, whereas the entities themselves are common to all languages. When you add an entity value, it only applies to the current language in your project. To support language-specific requests, choose the desired language from the menu near the name of the project, and add literal-value pairs as required.

When you attempt to delete the last literal for a specific value, Mix warns you that you will be permanently deleting not only the (last) literal but also the entity value itself for the current languages, and prompts you to confirm the deletion.

In a dialog that collects a list entity, the next step might need to be different for each possible value, or it might be the same for all possible values. It is also possible for your application to perform exclusive actions for some values, and proceed via a common path for all other values. You determine the required behavior for a list entity—that is, whether all values are handled the same way, or individual values determine different paths—when you set up the question and answer node that collects the entity.

Global command entity

If your application should support global commands (for example, Goodbye, Main menu, Operator), you must reserve an entity to hold recognized command values. This entity becomes the global command entity for your project.
You can also use this entity to extend the scope of specific question and answer nodes, by defining local command overrides. In a question and answer node, command overrides allow you to:

• Override global or channel-level handling for specific commands
• Handle custom commands
• Supplement the intent or entity in focus by allowing the node to recognize additional values

Dynamic list entities

When you create your NLU model, you might realize that, for some list entities, the set of values can only be fully determined at runtime. For example, the set of contacts for a user is specific to that user. Another example is the list of products available at a specific location (such as the restaurant branch closest to the user’s current position), or on specific occasions (seasonal products, holiday products), and so on.

Depending on the number of possible values for a dynamic list entity, you can use inline resources (compiled at runtime) or precompiled resources.

• Entity with up to 100 values: For example, the number of bank accounts for a typical person, or the number of rooms in a house, are typically between 5 and 10. Define a dynamic list entity, and rely on the client application to make additional literal-value pairs available to the dialog, at runtime, via a variable of type Dynamic Entity Data fetched from a data access node. See the workflow for using inline resources.
• Entity with more than 100 values: For example, the number of contacts one might have on their phone could be several hundreds; the number of doctors in a hospital could be thousands. Define a dynamic list entity, and rely on the client application to provide references to the corresponding precompiled resources, via the ExternalResourceReferences session variable. See the workflow for using precompiled resources.

Workflow for using a dynamic list entity (inline resources)

1. Add a list entity, and mark it as dynamic.
2. Add a few representative literal-value pairs for the entity.
3. Create a variable of type Dynamic Entity Data.
4. Set up a data access node using your dynamic entity data variable to get additional values for your dynamic entity, from the appropriate external system, at runtime.
5. Set up a question and answer node to collect your dynamic list entity.
6. In Mix.nlu, make sure you have annotated some samples with your dynamic list entity, and that your NLU model has been trained.
7. Preview your dialog design.
   When the dialog reaches the data access node that is meant to return the dynamic entity data variable:
   1. Choose the dynamic list entity to be extended with data from your dynamic entity data variable.
   2. Use the fields that appear to enter literal-value pairs (and define interactive elements if needed).
      Tip: Use Copy to Clipboard and save the JSON representation of the stub data, to be able to use the JSON bulk input feature the next time you must provide stub data at this data access node.

Dynamic entity data specification

The Nuance Mix Platform’s NLU and ASR services support dynamic list entities by using inline wordsets. In Mix.dialog, when using the TRY tab to preview your dialog design, the stub data you provide at a data access node is a JSON representation that includes both the inline wordset and data to support interactivity.

For more information on using wordsets to extend your NLU and ASR models, refer to the gRPC API documentation for NLU as a Service, and ASR as a Service.

Dynamic entity data variable object

Represents a dynamic entity data variable returned by a data access node.

{
    "moreCoffeeTypes": {
        "COFFEE_TYPE": [{
                "canonical": "cold brew",
                "literal": "cold brew"
            }, {
                "canonical": "iced cappuccino",
                "literal": "iced cappuccino"
            }
        ]
    }
}

Dynamic entity data object

Represents dynamic entity data for a dynamic list entity.

Dynamic entity data item

Represents an additional value for a dynamic list entity, and attributes to support interactivity for the value.

Workflow for using a dynamic list entity (precompiled resources)

1. Add a list entity, and mark it as dynamic.
2. Add a few representative literal-value pairs for the entity.
3. In Mix.nlu, add a few samples to the NO_INTENT intent, and annotate them with your dynamic list entity.
   These samples and literal-value pairs allow you to preview your dialog design directly in Mix.dialog. They are ignored at runtime.
4. In your dialog design, identify the context where the external data is relevant, and set up a data access node or an external actions node with the predefined variable ExternalResourceReferences as a Get data parameter, to fetch references to compiled ASR and NLU resources from the appropriate external system.

Relationship entities

A relationship entity has a specific relationship to an existing entity, either the isA or hasA relationship. For example, for an airline application, the entities that represent departure and arrival airports typically have the same possible values. If you first create a list entity (for example, CITY) to represent all the airports served by the airline, you can share its definition with other entities meant to represent departure and arrival cities by making these isA relationship entities: for example, ORIGIN isA CITY, and DESTINATION isA CITY. Assuming your NLU model has representative samples annotated with ORIGIN and DESTINATION, the application will be able to recognize what a user means when they say, for example, “I would like to book a flight to Barcelona from Helsinki.” Refer to the Mix.nlu documentation for more information.

Freeform entities

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. Unlike other entity types, for which the keywords in the user input that allow the NLU service to recognize an entity are directly associated with the entity values, a freeform entity is like a black box—at runtime, the NLU service relies on the surrounding text to identify where the entity itself starts and ends. When the user says, for example, “Send Joe this message: I’ll be there tonight,” the words “this message” are what tells the NLU service that what follows is the freeform entity to collect. The value attribute of a freeform entity is always empty—therefore, if your dialog design involves collecting freeform entities, make sure to refer to their literal or formatted literal attributes instead. Refer to the Mix.nlu documentation for details.

Regex-based entities

A regex-based entity represents a sequence of characters matching a pattern defined by a regular expression. For example, account numbers, postal/zip codes, order numbers, and other pattern-based formats. Refer to the Mix.nlu documentation for details.

Rule-based entities

A rule-based entity defines a set of values based on a GrXML grammar file. Refer to the Mix.nlu documentation for detailed information.

Anaphoras

The dialog context service supports resolving anaphoras recognized by your project’s NLU model, such as “there” (REF_PLACE), “then” (REF_TIME), or “her” (REF_PERSON) to a corresponding entity value that was previously collected (up to the previous two recognition steps) in the dialog flow. Once anaphoras have been tagged and your model trained in Mix.nlu, your dialog can handle them automatically. You do not need to configure anything in your dialog model. At runtime, the dialog uses the data that is has available to determine how to resolve the anaphora. Refer to the Mix.nlu documentation for details.