The Mobile & Digital Assistant Blog covers the latest in mobile and conversational AI development and engagement

TechExchange Quick-Tip: Understanding Oracle Digital Assistant Skill Entity Properties - Or, What Does "Fuzzy Match" Do?

Frank Nimphius
Master Principal Product Manager

article by Frank Nimphius, February 2020


Entities in Oracle Digital Assistant extract information from user messages based on patterns or values they represent. Users can have a natural conversation with a chatbot as they will only be prompted for information they have not yet provided. "I like a scoop of strawberry ice cream " implies the intent (to buy ice cream), the flavor (strawberry) and the size (a scoop). The only prompt to display for this example would be "how would you like to pay?".  By various examples, this article explores and explains properties you can set on custom entities. 

The Sample Skill (Starter Skill)

The starter sample skill you can download for this article contains a single entity "Pastas" and two dialog flow states. For the feature demonstrations in this article, there s no need for natural language processing (NLP). However, it is important to clarify that the functionality introduced in the following does work the same if intents and NLP are in the picture. 

The dialog flow (image below) uses the System.ResolveEntities component to render the user interface. The System.ResolveEntities component doesn't require a lot of properties to set and instead gets its property setting directly from the entity. 

The System.Output component in line 22 has its text property set to an Apache FreeMarker expression that either prints a single value or multiple values (later more about this)

Note: that you could use the System.CommonResponse component instead of the System.ResolveEntities component. 

When you run the skill in the Oracle Digital Assistant integrated skill conversation tester, then you see a list of values like shown below (image below). The Pastas entity in the sample is a value-list entity with 11 pasta entries.

Note that it is only the Webhook channel setting in the conversation tester that renders all 11 entries. If you e.g. switch to the Facebook simulation, then the list gets split according to the maximum allowed action buttons in Facebook. However, please keep the Webhook channel for this. 

Selecting a single entry from the list, or typing its value, will then print the confirmation as shown in the image above. 

As mentioned, the sample skill uses a single entity Pastas. 

Properties Overview

The first three properties you see when selecting the Pastas entity are self-explaining. Each entity must have a unique name, optionally a description and also a type set. In this example, the type is set to Value list

Enumeration Range Size

As mentioned earlier, not all channel support 11 list items in a list of values or a card layout. So dependent on the channel you use with your bot, or as a general design decision, you may need to reduce the overall number of items to be displayed. In this example, I set the range size to 4, which means that only 4 items are displayed in the list at a time. The System.RespoveEntities component shows a Show More button if there are more values to query. 

Note: All 11 items are accessible with this setting. So there is no restriction to the displayed values

Good to know: You can also use Apache FreeMarker expressions to set the enumeration range size. This makes it easy to set range sizes per channel type. 

At runtime, the list that previously had shown 11 values, now displays 4 values. 

Error Message

The error message property allows you to define a error message that is displayed when the user enters an invalid value. For example, the Pastas entity doesn't validate sports like Rugby correct. So entering a value like Rugby will display an error message that gets added in front of the prompt message. In the example I use Apache FreeMarker to display the user input as part of the error message (image below).

At runtime, initially the default prompt of the entity is displayed. Then, when a user types an invalid message into the Message field, the list component re-renders the list with the error message put in front (second list in the image below).

Note:  You can use Apache FreeMarker to reference entries in a resource bundle from the error message field. For this, make sure you define a variable of type "resourcebundle" in the dialog flow. If this variable was named "rb", then the expression to use in the error message field would be: ${rb.key_name}, or ${rb('key_name','argumen_1','qrgument_2','argument_n')}

Disambiguation Prompt

The disambiguation prompt is displayed when a user selects multiple values (e.g. two pastas) where she is allowed a single value only. Because the user selected two values, a dialog is shown for her to select the pasta she really wants.

The image below shows the disambiguation prompt property in action. After the initial value list displayed, the user types in a message that contains two pastas: Bacon Pasta and Beef Ragout. Because of this the disambiguation dialog shown in the image below is displayed. 

Note: As with the error message field, the disambiguation prompt can use Apache Freemarker and also reference resource bundle. A message string like ${profile.firstName}, please choose your pasta would display a message like "Frank, please choose your pasta" if the profile's firstName variable is set to "Frank"

Fuzzy Match

The way entity extraction works is that a value is extracted from a user message if the message contains a value that fully matches an entity value or one of its synonyms (case doesn't matter). Fuzzy match broadens the entity match to partial matches. 

When the Fuzzy Match property is enabled, then a partial match is good enough to extract entity values. In the image below, "beef" is contained in multiple entity values. As a result, the disambiguation dialog is shown listing all entity values that contain the word "beef". 

Multiple Values

It is very common that orders - especially when ordering pasta - contain multiple products. So instead of displaying a disambiguation dialog, in this case you want to accept all selected pasta items. Fo rthis, you enable the Multi Value property. 

At runtime, when a user types multiple values or, with Fuzzy Match enabled, sends a message that resolves to multiple values, then all of these values are accepted (see image below)

The image below shows the multiple values use case for when the user explicitly asks for two products displayed in the list.


The prompts property allows you to define one or many strings to be displayed as a prompts. If you define sequence numbers (as in the image below), then the different prompts are shown in that sequence. If you don't provide a sequence, then strings are randomly chosen and displayed. The idea is to make the bot appear less robotic in its answers. 

The image below shows the sequential prompts in action. Initially the prompt defined as sequence 1 is displayed. When the the user enters an invalid list value - like Rugby - then the list is re-rendered again with an error message (if set). As you can see though, the re-rendering uses the prompts defined as second in the prompt sequence. After the next failed value input, eventually the 3rd prompt is displayed. 

Note: prompts can use message bundle references too. Message bundles are recommended for multi lingual bots but also to manage strings in a central location

Validation Rules

The last property to introduce for entities are Validation Rules. You can use the validation rules property to define one or many validations. Validations use Apache freeMarker expressions and return false for a failed validation and true for a successful validation. 

Using Composite Bag Entities

By the time of writing, validation rules on custom entities cannot access values the entity extracted from the user message. This however is required if you want to evaluate the content of the extracted entity values. If, for example, a user can order multiple pastas, but not more than 2, then this can be implemented using validation rules. Other 

The work around to the problem that exist for custom entities also is a recommendation of best practice: Wrap custom entities into a composite bag entity. Composite bag entities allow you to group one or many entities into business domain objects, which then can be resolved within a single dialog flow state. Because composite bag entities provide functionality that is not available for plain entities, you should always wrap your plain entities in composite bag entities. 

As shown in the image below (and available in the completed skill you can download for this article), the composite bag entity I created is named "PastasCBE". 

The composite bag entity has a single bag item "Pastas", which is a reference to the Pastas entity I used so far. 

The composite bag item copies all settings from the entity it references. To make validation rules work, I did overwrite the property for the composite bag item. As you can see in the image below, the Apache FreeMarker expression first checks if the extracted value is an array (which indicates multiple values). If multiple values are found, then the expression checks for whether there are more than two items selected, in which case false is returned. 

The change to Composite Bag Entities requires little changes to the dialog flow. First change is the type of the pastas variable, which needs to be set to the name to the composite bag entity. 

The second change to the dialog flow is within the System.Output component. The text property still references the pastas variable, but needs to reference the name of the entity bag item as well. To keep things simple, I named the entity bag item "Pastas", same as the referenced entity. So pastas.value.Pastas now gives you access to the extracted values. 

Download Sample Skills

Starter Skill (to Follow Instructions)

Completed Sample Skill


Related Content

TechExchange: How-to Use the System.ResolveEntities Component in Oracle Digital Assistant

TechExchange-QuickTip: Creating Multi-Select Lists in Oracle Digital Assistant

TechExchange: Building Value Lists From Entities Using The Common Response Component - A Generic Approach

TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube


Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.