Oracle Cloud Infrastructure Documentation

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. 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 a combination of the following:
  • part before the at (@) symbol:
    • uppercase and lowercase letters in the Latin alphabet (A-Z and a-z)
    • digits (0-9)
    • the following printable characters: !#$%&'*+-/=?^_`{}~
    • dot (.)
  • part after the at (@) symbol:
    • uppercase and lowercase letters in the Latin alphabet (A-Z and a-z)
    • digits (0-9)
    • hyphen (-)
ragnar.smith@example.com
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. 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. Within your dialog flow definition, you can use these properties to isolate a specific facet of an entity value. For example, ${addressVariable.value.road} outputs Smith Road from the input, 500 Smith Road, Smithville.

Entity Name Content Extracted Examples Properties (Referenced in Value Expressions) Example NLU Engine Response
ADDRESS The city, house number, and road 500 Smith Road, Smithville
  • city

  • houseNumber

  • road

  • originalString

{
"road": "smith road",
"city": "smithville",
"entityName": "ADDRESS",
"houseNumber": "500",
"originalString": "500 Smith Road, Smithville"
}
DATE An absolute or relative date.
Note: When the user input names a day, but provides no other temporal context, the system considers this a future date. For example, it considers Wednesday in the following input as next Wednesday, not the current Wednesday or the prior Wednesday.
  • Book me a ticket for Wednesday.

  • I want to file an expense report for Wednesday.

To override this default behavior, you can implement a custom component (as you might for the first example) and/or add prompts to the dialog flow. Including the DATE entity in a composite bag allows you to enhance it with disambiguation prompts, error messages, and validation rules.
  • November 9, 2016

  • Today

  • originalString

  • date

{
"date" : 1539734400000,
"entityName" : "DATE"
"orginalString" : Wednesday, "October 17, 2018"
}
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 endpoints of a time interval
  • 4 years

  • two weeks

  • startDate

  • endDate

  • originalString
{ "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",}
PERSON Recognizes the first, middle, and last names of people, including fictional characters.

The PERSON entity can't match names that are also locations (for example, Virginia North).

  • John J. Jones
  • Ashok Kumar
  • Gabriele D'Annunzio
  • Jones, David
  • Cantiflas
  • Zhang San
  • Virginia Jones
  • originalString

  • name

"PERSON": [ { "originalString": "John J. Johnson", "name": "john j. johnson", "entityName": "PERSON" } ]
LOCATION Extracts location-related terms from the user's input, such as roads, trajectories, regions, various types of structures (bridges, ports, dams), public places, and commercial properties.

Ask your administrator to enable this entity in Settings > Feature Management if it's not available in the UI.

  • Reno
  • Rancho Seco
  • Nimbus Dam
  • War Memorial Opera House
  • Virginia North
  • Virgina Beach
  • originalString

  • name

"LOCATION": [ { "originalString": "Virginia North", "name": "virginia north", "entityName": "LOCATION" } ]

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.

Composite Bag

A composite bag illustrates a larger concept, like a business domain, by grouping together related entities along with other items that store location and accept free text and attachments. You can configure the composite bag entity to resolve its constituent items in different ways: it can prompt for individual entity values when they're missing from the user input, for example, or it can use the value extracted by one if its entities to resolve a second entity.

Value List Entities

An entity based on a list of predetermined values, like menu items 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.

Dynamic Entities

Dynamic entities are entities whose values can be updated even after a skill has been published.

Like value list entities, dynamic entities are enum types. However, dynamic entities differ from value list entities in that their values are not static; they may be subject to frequent change. Because of this – and also because dynamic entities can contain thousands of values and synonyms – the values are not managed in the UI. They are instead managed by the Dynamic Entities API (described in REST API for Oracle Digital Assistant).

Regular Expression

Resolves an entity using a regular expression (regex), such as (?<=one\s).*(?=\sthree). Regular expressions allow your skill to identify pre-defined patterns in user inputs, like ticket numbers. Unlike the other entity types, regex-based entities don’t use NLP because the matching is strictly pattern-based.

Entity List

A super set of entities. Using a travel skill 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 skill 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.

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). 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.

Create Entities

To create an entity:
  1. Click Entities (This is an image of the Entities icon.) in the side navbar.
  2. Click Add Entity and then enter the name and select the type, such as Value List, or Derived.
  3. You can add the following functions, which can be overwritten if you add the entity to a composite bag.
    • If a value list entity has a long list of values, but you only want to show users only a few options at a time, you can set the pagination for these values by entering a number in the Enumeration Range Size field, or by defining an Apache FreeMarker expression that evaluates to this number. For example, you can define an expression that returns enum values based on the channel.

      When you set this property to 0, the skill won't output a list at all. It expects user input instead. With that in mind, you might want to set this property to 0 when you add the entity to a composite bag, because prompting for values results in a more conversational experience than can a list of values.

      If you set this number to one lower than the total number of values defined for this entity, then the System.resolveEntities component displays a Show More button to accompany each full set of values. If you use the System.CommonResponse component to resolve the entity, then you can configure the Show More button yourself.
      This is an image of the Show More button.
      You can change the Show More button text using the showMoreLabel property that belongs to the System.ResolveEntities and the System.CommonResponse component.

    • Add an error message for invalid user input. Use an Apache FreeMarker expression that includes the system.entityToResolve.value.userInput property. For example, ${system.entityToResolve.value.userInput!'This'}' is not a valid pizza type.
    • To allow users to pick more than one value from a value list entity, switch on Multiple Values. When you switch this on, the values display as a numbered list.
      This is an image of the numbered multi-value list.
      Switching this option off displays the values as a list of options, which allows only a single choice.
    • Switching on Fuzzy Match increases the chances of the user input matching a value, particularly when your values don’t have a lot of synonyms. Switching this off enforces strict matching, meaning that the user input must be an exact match to the values and synonyms; “cars” won’t match a value called “car”, nor will “manager” match a “development manager” value.
    • To force a user to select a single value, switch on Prompt for Disambiguation and add a disambiguation prompt. By default, this message is Please select one value of <item name>, but you can replace this with one made up solely of text (You can only order one pizza at a time. Which pizza do you want to order?) or a combination of text and FreeMarker expressions. For example:
      "I found multiple dates: <#list system.entityToResolve.value.disambiguationValues.Date as date>${date.date?number_to_date}<#sep> and </#list>. Which date should I use as expense date?"
    • Define a validation rule using a FreeMarker expression.
      Note

      You can only add prompts, disambiguation, and validation for built-in entities when they belong to a composite bag.
  4. Next steps:
    1. Add the entity to an intent. This informs the skill of the values that it needs to extract from the user input during the language processing. See Add Entities to Intents.
    2. In the dialog flow, declare a context variable for the entity.
    3. Access the variable values using Apache FreeMarker expressions. 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 (This is an image of the Entities icon.) in the side navbar.

  2. Click More, choose Import Value list entities, and then select the .csv file from your local system.
    Description of import_entities.png follows
    Description of the illustration import_entities.png

  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 (This is an image of the Entities icon.) in the side navbar.

  2. Click More, choose Export Value list entities and then save the file.
    Description of export_entities.png follows
    Description of the illustration export_entities.png

    The exported .csv file is named for your bot.

Composite Bag Entities
Composite bag entities allow you to write much shorter, more compact dialog flow definitions because they can be resolved using just one component (either System.ResolveEntities or System.CommonResponse). We recommend that you use this approach, because you don't need components like System.Switch, System.setVariable, System.Text, or System.List to capture all of the user input that's required to perform some business transaction. Instead, a single component can prompt users to provide values for each item in the bag. The prompts themselves are condition-specific because they're based on the individual configuration for each bag item. Using the composite bag entity, Apache FreeMarker, and either the System.CommonResponse and System.ResolveEntities components, your skill can:
  • Capture all free text, allow file uploads, and collect the user's current location with the STRING, ATTACHMENT, and LOCATION items.

  • Execute individual behavior for each member entity in the bag–You can add value-specific prompts and error messages for individual entities within the composite bag (which includes custom entities, system entities, and the STRING, ATTACHMENT, and LOCATION items). You can also control which entities should (or shouldn't) match the user input. Because you can create a prompt sequence, the skill can output different prompts for each user attempt.

  • Present multi-select pick lists.

  • Validate value matches based on validation rules.

  • Support for the unhappy flow–Users can correct prior entries.

  • Execute temporary, match-based transitions–The dialog flow can temporarily exit from the component when an entity has been matched, so that another state can perform a supporting function like a REST call. After the function completes, the dialog flow transitions back to the component so that the value matching can continue. For example:
    • After a user uploads a receipt, the receipt itself needs to be scanned so that values like expense date, amount, and expense type can be extracted from it for the other entities in the bag. This allows the component to fill the rest of values from the receipt, not from any user input.

    • The skill outputs a message like, “Almost there, just a few more questions” in between matching sets of entities in the bag.

    • The user input must be validated through a backend REST call. The validation might be required immediately, because it determines which of the bag items must prompt for further user input. Alternatively, the call might return information that needs to be shared with the user, like an out-of-policy warning.

    To find out how the transitionAfterMatch property that enables this functionality, see System.CommonResponse and System.ResolveEntities.

  • Disambiguate values–You can isolate a value from the user input through entity-specific prompts and component properties. These include support for corrections to prior input (the “unhappy” flow) and for prompting user input for specific built-in entity properties.

You can’t add these functions using the System.Text or System.List components. You can use these components for primitive values, but, as noted in Comparison of Dialog Flow Definitions, the System.ResolveEntities and System.CommonResponse components provide a streamlined alternative for resolving entities and non-entity values.
Explore the CbPizzaBot Skill
The CbPizzaBot skill gives you a taste of how a composite bag and System.CommonResponse component to output responses based on input values.
  • Customized Messages–Each value for the PizzaType entity is rendered as a card.

  • Global Actions–Whenever you enter an invalid value, the skill adds a value-specific error message to the card and a Cancel button, which lets you exit the dialog.

  • Multi-Value Pick List–The Toppings entity is rendered as a paginated list of values. Entering 7 (Extra Cheese) triggers a conditional message, which is a single-value list.

  • Location–The skill prompts for, and collects, the user’s coordinates (longitude and latitiude).

This skill doesn’t use any custom components for this functionality. Instead, this functionality is created declaratively.
Create a Composite Bag Entity
  1. Click Entities (This is an image of the Entities icon.) in the side navbar.

  2. Click Add Entities.

  3. Choose Composite Bag as the entity type.

  4. Enter the name and description.

  5. Click + Bag Item to open the Add Bag Item dialog. If you’re adding a built-in entity or an existing custom entity, you can create a bag-specific name for it and add a description of its role within the context of the composite bag.

  6. You can fill the bag with custom entities, built-in entities and the following:
    • STRING—Captures free text from the user.

    • LOCATION—Captures the user’s location. It stores this as a JSON object with two properties: longitude and latitude.

    • ATTACHMENT—Accepts files, audio files, video, or image files uploaded by the user. The composite bag entity stores the URL where the attachment is hosted.

    Note

    The items get resolved in the order that you add them. However, the sequence can be affected depending on how you configure individual members of the composite bag.
  7. Clicking Close returns you to the Entities page, but you can add other bag-specific capabilities to the item first (or update it later by clicking This is an image of the Edit icon. in the Entities page).

  8. Next steps:
    • Add individual error messages, disambiguation prompts, or conditional prompting for the bag items.
    • Add the entity to an intent. See Add Entities to Intents.

    • Configure the dialog flow to use the composite bag entity. See Configure the Dialog Flow for Composite Entities and use the CbPizzaBot as a reference if you’re using the System.CommonResponse component.

Add Prompts
You can add a single prompt, or create a sequence of prompts, each providing increasingly specific information for each time the user enters an invalid value. To add these prompts:
  1. By default, the Prompt for Value field is populated with true to enable prompting, but by setting this to false, you can prevent explicit prompting. To prompt for a conditional value, add a boolean FreeMarker expression that evaluates to either true or false.

    Tip:

    Even when you set the field to false, the item can still be resolved as part of another item that’s being prompted for when you switch on Out of Order Extraction.
  2. Click Add Prompt to build the prompt sequence. You can reorder it by shuffling the fields through drag and drop gestures, or by renumbering them. You can randomize the output of the prompts when you give two or more prompts the same number. You can store prompts in resource bundles (for example, ${rb.askCheese}), or write them as combinations of text and FreeMarker expressions.
    Note

    You can only add prompts for built-in entities when you add them to a composite bag.
Enable Out-of-Order Extraction

The Out of Order Extraction option enables your skill to accept changes to previously entered values in mid-conversation and continue on. For example, the PizzaSize entity might be resolved when a customer enters I want a large pizza. However, when the composite bag prompts for the PizzaType entity, the customer might then reply Veggie please, but make it a medium. The skill can update the PizzaSize entity value with medium without restrarting the conversation because the Out of Order Extraction option is enabled for the bag's PizzaSize and PizzaType items.

Switch off Out of Order Extraction to prevent inadvertent matches. If you switched this option on for a STRING item, for example, the first user message would be stored by this item instead of getting matched by intended entity (which might be the first entity in the bag).

Enable Extract With
Use the Extract With option to enable your skill to resolve one bag item using the input entered for a second item in the bag. This option, which allows your skill to handle related values, provides greater flexibility for user input. Users can enter home instead of a full address, for example. Here's how:
  • The composite bag has two address-related entities: NamedAddress, a list value entity with values like home and office, and DeliveryAddress, an ADDRESS entity.
  • The DeliveryAddress entity's prompt is Where do you want that delivered?
  • The NamedAddress entity does not prompt for input (false is entered in the Prompt for Value field).
  • The NamedAddress entity can be extracted with DeliveryAddress (DeliveryAddress is selected from the Extract With menu).

When the composite bag prompts for the DeliveryAddress entity, it can resolve the entity using either a physical address, or one of the NamedAddress list values ( home or office).

Add Validation Rules
Each item in the bag can have its own validation rules. You can add a validation rule by first clicking +Validation Rule and then adding a FreeMarker expressions and a text prompt. The expression uses the following pattern to reference the item value, where varName is the name of the composite bag entity that’s declared as a context variable in the dialog flow definition:
${varName.value.itemName}
If this expression evaluates to false, then the user input is not valid.
The following example of a validation expression is for a item called Amount. It’s a built-in entity, CURRENCY. To return a number amount for the comparison, the expression adds the CURRENCY entity’s amount property:
${expense.value.Amount.amount > 4}
The corresponding validation message can also reflect the user input through a FreeMarker expression. For example, the following message uses the type of currency extracted from the user's input as part of the validation message:
Amounts below 5 ${expense.value.Amount.currency} cannot be expensed. Enter a higher amount or type 'cancel'.
To find out about other CURRENCY properties (and the other built-in entity properties as well), see Complex Entities.
Configure the Dialog Flow for Composite Entities
  1. In the context node, declare the composite bag entity as a variable:
    ...
    metadata:
      platformVersion: "1.1"
    main: true
    name: "ExpenseBot"
    context:
      variables:
        expense: "Expense"
        iResult: "nlpresult"
  2. You can use System.ResolveEntities or System.CommonResponse . Both of these components let you leverage the composite bag entity and both provide their own benefits. The System.ResolveEntities is the simpler of the two, having a small set of properties. Unlike the System.ResolveEntities component, the System.CommonResponse provides you with more control over the UI that’s used to resolve the entities in the bag. For example, you can add conditional logic to determine prompts and value-related global actions.

  3. Reference the composite bag entity context variable in the component’s variable property (such as expense in the following examples) and then define the other properties as needed. System.ResolveEntities and The Component Properties describe them and provide further examples.

    Here’s an example of the System.ResolveEntities component:
    resolveExpense:
      component: "System.ResolveEntities"
      properties:
        variable: "expense"
        nlpResultVariable: "iResult"      
        cancelPolicy: "immediate"
        transitionAfterMatch: "false"
        headerText: "<#list system.updatedEntities.value>I have updated <#items as ent>${ent.description} to ${expense.value[ent.name]}<#sep> and </#items>. </#list><#list system.outOfOrderMatches.value>I got <#items as ent>the ${ent.description}<#sep> and </#items>. </#list>"
      transitions:
        next: "thankYou" 
    Here’s an example of the System.CommonResponse component. To activate the Show More option, you must configure the label with action defined with the system variable, system.showMore (action: "system.showMore" in the following example).
    resolveExpense:
      component: "System.CommonResponse"
      properties:
        processUserMessage: true
        variable: "expense"
        nlpResultVariable: "iResult"      
        cancelPolicy: "immediate"
        transitionAfterMatch: "false"
        metadata:
          responseItems:        
          - type: "text" 
            text: "<#list system.entityToResolve.value.updatedEntities>I have updated <#items as ent>${ent.description}<#sep> and </#items>. </#list><#list system.entityToResolve.value.outOfOrderMatches>I got <#items as ent>${ent.description}<#sep> and </#items>. </#list>"
          - type: "text" 
            text: "${system.entityToResolve.value.prompt}"
            actions:
            - label: "${enumValue}"
              type: "postback"
              iteratorVariable: "system.entityToResolve.value.enumValues"
              payload:
                variables:
                  expense: "${enumValue}"
              visible:
          globalActions:
          - label: "Show More"
            type: "postback"
            visible:
              expression: "${system.entityToResolve.value.needShowMoreButton}"
            payload:
              action: "system.showMore"
              variables:
                ${system.entityToResolve.value.rangeStartVar}: ${system.entityToResolve.value.nextRangeStart}
          - label: "Cancel"
            type: "postback"
            visible:
              onInvalidUserInput: true
            payload:
              action: "cancel"
      transitions:
        actions:
          cancel: "ShowMenu"
          match: "afterMatch"
        next: "thankYou" 
Comparison of Dialog Flow Definitions
Because composite bag entities are modeled as a single unit, they simplify your dialog flow definition.
Task Individual Entities Composite Bag Entity
Declaring context variables. You declare context variable for several entities:
context:
  variables:
    size: "PizzaSize"
    type: "PizzaType"
    crust: "PizzaCrust"
    iResult: "nlpresult"
You declare the composite bag entity:
context:
  variables:
    pizza: "PizzaBag"
    iResult: "nlpresult"
Defining states for setting variable values. You need to define a series of states components that set values and prompt user input, such as:

When you use the nlpResultVariable property with System.List and System.Text components, you don’t need to add separate System.setVariable components.

You only need to define a single state for the System.CommonResponse component or the System.ResolveEntities component to resolve all of the entity values.
  resolvePizza:
    component: "System.ResolveEntities"
    properties:
      variable: "pizza"
      nlpResultVariable: "iResult"      
Referencing values for output text. Use ${variable name.value}expressions.
  done:
    component: "System.Output"
    properties:
      text: "Your ${size.value} ${type.value} Pizza is on its way."
    transitions:
      return: "done"
Reference the context variable declared for the composite bag entity and the item within the bag: ${varName.value.itemName}:
  done:
    component: "System.Output"
    properties:
      text: "Your ${pizza.value.PizzaSize?lower_case} ${pizza.value.PizzaType?capitalize} with ${pizza.value.PizzaCrust?lower_case} crust and ${pizza.value.CheeseType?capitalize} cheese is on it's way"
    transitions:
      return: "done"
The system.entityToResolve Variable
The system.entityToResolve variable tracks an entity value. You can use it to define the logic for an entity's error message, or for various properties that belong to the System.resolveEntities and System.CommonResponse components. Append the following properties to return the current entity value:
  • userInput
  • prompt
  • promptCount
  • udpdatedEntities
  • outOfOrderMatches
  • disambiguationValues
  • enumValues
  • needShowMoreButton
  • rangeStartVar
  • nextRangeStart
Here's an example of using this variable to return the current user input in an entity's error message:
Sorry,'${system.entityToResolve.value.userInput!'this'}' is not a valid pizza size.
Here's an example of using various system.entityToResolve definitions. Among these is a message defined for the text property, which confirms an update made to a previously set entity value using an Apache FreeMarker list directive and the updatedEntities property.
    metadata:
      responseItems:        
      - type: "text" 
        text: "<#list system.entityToResolve.value.updatedEntities>I have updated <#items as ent>${ent.description}<#sep> and </#items>. </#list><#list system.entityToResolve.value.outOfOrderMatches>I got <#items as ent>${ent.description}<#sep> and </#items>. </#list>"
      - type: "text" 
        text: "${system.entityToResolve.value.prompt}"
        actions:
        - label: "${enumValue}"
          type: "postback"
          iteratorVariable: "system.entityToResolve.value.enumValues"
For global actions, this variable controls the Show More global action with the needShowMoreButton, rangeStartVar, and the nextRangeStart properties:
        globalActions: 
        - label: "Show More"
          type: "postback" 
          visible:
            expression: "${system.entityToResolve.value.needShowMoreButton}"
          payload:
            action: "system.showMore"
            variables: 
              ${system.entityToResolve.value.rangeStartVar}: ${system.entityToResolve.value.nextRangeStart} 
        - label: "Cancel"
          type: "postback" 
          visible:
            onInvalidUserInput: true
          payload:
            action: "cancel"
The Show More label must include a system.showMore (action: "system.showMore"). Otherwise, it won't function.
entityToResolve Expressions
Expression Description
${system.entityToResolve.value.resolvingField} Returns the name of the bag item.
${system.entityToResolve.value.allMatches[0].entityName} Returns the entity name that's referenced by the bag item. The allMatches array contains all of the entities whose values could potentially be updated by the user's message.
${<variable>1.value[system.entityToResolve.value.resolvingField]} Returns the bag item value that users enter or select.
${system.entityToResolve.value.userInput} Returns the text entered by the user. You can use this expression to log the user input or display it in the chat, for example, when a user enters an invalid value.
${system.entityToResolve.value.outOfOrderMatches[n].entityName} Returns the name(s) of the entities that are extracted out-of-order. Along with the values that the System.ResolveEntities or the System.CommonResponse components prompt for, users may provide additional values that trigger out-of-order value extraction and updates to other entities in the composite bag.
${system.entityToResolve.value.outOfOrderMatches[n].name} Returns the name of the composite bag item.
${system.entityToResolve.value.outOfOrderMatches? has_content?then(…,…)} Returns the value of an entity that has been matched out of order. Because it's likely that no entity has been matched out of order, this expression uses the has_content operator.
Tutorial: Real-World Entity Extraction with Composite Bag Entities

You can get a hands-on look at creating a composite bag through this tutorial: Enable Real-World Entity Extraction with Composite Bag Entities.

Create Dynamic Entities

Dynamic entity values are managed through the endpoints of the Dynamic Entities API that are described in REST API for Oracle Digital Assistant. To add and modify the entity values and synonyms, you must first create a dynamic entity to generate the entityId that's used in the REST calls.

To create the dynamic entity:
  1. Click + Entity.
  2. Choose Dynamic Entities from the Type list.
  3. If the backend service is unavailable, hasn't yet pushed any values, or if you do not maintain the service, click + Value to add mock values that you can use for testing purposes. These values will get overwritten when the services pushes data to the skill.
  4. Click Create.

Tip:

If the API refreshes the entity values as you're testing the conversation, click Reset to restart the conversation.
A couple of notes for service developers:
  • You can query for the dynamic entities configured for a skill using the generated entityId with the botId. You include these values in the calls to create the push requests and objects that update the entity values.
  • An entity cannot have more than 10,000 values. To reduce the likelihood of exceeding this limit when you're dealing with large amounts of data, send PATCH requests with your deletions before you send PATCH requests with your additions.

Entity List

A super set of entities. Using a travel skill 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 skill 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.