Skip to main content

Entities

An Entity is a building block which contains a collection of entries, typically words or lists that have some characteristics in common. A typical example for such words include named entities, like cities or product names. The entries of the Entity are then used to identify when the Entity should match, which helps your bot understand what the user said.

The sections on this page provide information about the various aspects of Entities:

Concept​

An Entity is a building block which contains a collection of entries, typically words or lists that have some characteristics in common. A typical example for such words include named entities, like cities or product names, which are then used to identify when the Entity should match.

Entities can be used in TLML Syntax, Language Objects, Listeners, Matches, etc. to create more powerful natural language understanding. In many ways, they are similar to Language Objects.

When referenced in other components of Teneo, Entity names must be preceded with the percentage sign %.

An Entity is made up of the following components:

  • Entity name
  • Entry
  • (Optional) variables

An Entity can have as many entries as needed and each entry can be associated with zero or more variables. However, all entries must have the same type of variable.

Relevant data can be extracted from the user input via NLU variables; see Tips and Tricks for an example.

Naming an Entity​

The following conventions apply for naming an Entity:

  • An Entity's name must be unique within the solution.
  • The name must be written in upper case. Lower-cased characters are automatically upper-cased by Teneo.
  • The name cannot contain any reserved characters. Any special characters or blank spaces are automatically converted into underscores by Teneo.

The following conventions apply for naming an Entry:

  • The entry must be unique within the Entity. Teneo Studio prevents the user from saving the Entity if two entries have the same value.
  • Reserved characters used as entry values will automatically be escaped with quotes.
  • To use another Entity as an entry value, its name must be preceded by the percentage sign (%) and written in capitalized letters. Teneo Studio automatically capitalizes letters following %.

The following conventions apply for naming a variable:

  • The name cannot contain spaces or other special characters.
  • The variable cannot be named lob or _USED_WORDS since it conflicts with special variables.
  • A closing curly bracket used as a script variable value will automatically be escaped with a backslash.

Entity Matching​

The Longest Match option (:L) is implicitly applied to the Entity. The Longest Match option is used in TLML Syntax and it ensures that Engine evaluates the full syntax and selects the match with the maximum number of matched words. In other words, this type of behavior makes sure that substrings are not accidentally matched.

For example, given the following TLML Syntax and user input:

  • TLML Syntax: (york / (new >> york)):L
  • User input: "new york"

"new york" will match instead of "york".

Entities within a Solution​

When working in a solution, users have access to the following collections of Entities:

  • Entities built and stored within the solution, and
  • Entities available in any lexical resource assigned to the solution.

Entities stored in the solution are under full control of the Teneo Studio user and these can be managed and modified in any way. Entities from a pre-built lexical resource (e.g. Teneo Lexical Resources) can be viewed and used in TLML Syntaxes but not modified.

A full list of pre-built Entities can be found here.

info

If an Entity created in the solution shares its name with an Entity available through an assigned lexical resource, the Entity located in the solution is always chosen by Engine over the Entity from the assigned lexical resource.

Entries​

An entry is one row in the Entries Editor in an Entity.

The entry value can be either of the following:

  • a word
  • a sequence of words
  • a different Entity
  • a different Language Object

Internally, a sequence of words will be transformed into Teneo's condition syntax. For example, if the two words "Chai latte" are entered into the entry field of an Entity, they will be interpreted as Chai>>latte which means that the word "Chai" is directly followed by the word "latte" without any intervening word allowed in between them. However, this holds only for sequences of strings.

For any other combination of entries, e.g. sequences containing Entities or Language Objects concatenating multiple elements is not possible. If you want to add such a sequence (for example HOT.ADJ.LEX WATER.NN.LEX) to an Entity, you should create a new Language Object (here: HOT_WATER.ADJ.NN.MUL) that contains the sequence of these two Language Objects in its language condition. This multiword Language Object can then be added to be an entry of the Entity BEVERAGES_SERVED.ENTITY.

Variables​

You can assign an entry zero, one or more variables of type string or script. When a variable is added to one entry, all entries need to have a variable value:

  • String type variables are implicitly quoted and a variable value can be left empty when needed.
  • Script type variables can contain scripted values or manually quoted values.

When changing the type from script to string, quotes are added to the variable values; while changing from string to script, any leading or trailing quotes are removed from variable values and the implicit ones remain.

Create New Entity

How To​

Open an Entity​

You can open an existing Entity by:

  1. Navigating to the folder where the Entity is stored or, alternatively, open the list of available Entities from the Solution dashboard.
  2. Click the Entity name.
  3. The Entity is now opened.

Edit an Entity​

To edit an Entity in Teneo Studio Web, do the following:

  1. Navigate to the Entities panel on your Solution dashboard.
  2. Open one of the Entities and click Edit in the top right of the navigation bar.
info

If the Entity has been locked, it will not be possible to edit it. In that case, you may want to create a new Entity instead.

Create an Entity​

To create a new Entity, follow these steps:

  1. If in a folder, click the Create button and select Create new entity; if in the Entity list, simply click the Create new entity button.

Create New Entity

  1. The Create New Entity opens, write the Entity name and, optionally, an Entity description.
  2. Lastly, click Create Entity.

Save an Entity​

To save an Entity, follow these steps:

  1. Click Save in the top right corner of the window. Note that the Save button is only visible when changes have been performed.
  2. Optionally, add a comment.
  3. Click Save to confirm the save action or Cancel to abort the save.

Successful save is confirmed with a "Document saved successfully!" message; by clicking elsewhere in the browser window the message is closed.

Close an Entity​

To close an Entity in Teneo Studio Web:

  1. First, remember to Save if any changes were performed in the Entity to preserve these.
  2. Next, simply navigate back by using the back arrow of the browser.

Teneo Studio will prompt the user to save if unsaved changes are detected.

Delete an Entity​

To delete an Entity from the solution, follow these steps:

  1. Navigate to the folder where the Entity is saved.
  2. Hovering over the Entity, an icon of a recycle bin appears in the right side of the browser window, click it.
  3. The user will be prompt to confirm the deletion of the Entity:
    • Click Delete to perform a usage check before deletion.
    • Click Delete without usage check to delete directly.
    • Click Cancel to cancel the action.
info

The deletion of an Entity currently cannot be undone in Teneo Studio Web, for this action please refer to the Recycle Bin available in Teneo Studio Desktop.

Add Entries and Variables​

To add an entry in your Entity, please follow the below steps:

  1. On your Solution dashboard, navigate to the Entities panel.
  2. Choose the Entity where you wish to add a new entry.
  3. Click the Add entry button; this will add a new row to your entity.
  4. Remember to Save the Entity to preserve the changes.

To add a variable for your entry in Teneo Studio Web, follow the below steps:

  1. Click Add string variable or Add script variable.
  2. Give the variable a name by clicking New_Variable.
  3. Remember to Save the Entity to preserve the changes.
tip

Sorting by variable value is possible by clicking the arrow next to the three vertical dots.

See also the Entries editor.

Edit Entries and Variables​

Any existing entry value or variable can be modified by simply clicking the text field to update the value; pressing Enter allows to go to the next entry (move one line down) while pressing Tab allows to move to the next column.

To change the type of an already existing variable, follow the below steps:

  1. In the variable's header, click the three vertical dots.
  2. Next, click Change Type.
  3. The variable is now changed to Script/String (depending on which variable type it had before).
  4. Remember to Save the Entity to preserve the changes.

Delete Entries and Variables​

A line containing an entry can be deleted by clicking the x available at the line of the entry.

To delete a variable, simply follow the below steps:

  1. In the variable's header, click the three vertical dots.
  2. Next, click Delete variable.
  3. Remember to Save the Entity to preserve the changes.

Sort Entries and Variables​

To sort by a specific column, simply click the arrow icon available in the top of each column.

sort entries web

UI​

web entity window

The Entity window in Teneo Studio Web contains the following:

SectionDescriptionRelated Pages
Entity nameDisplays path and name of selected Entity.
SearchAllows the user to search for a specific entry in the Entries editor.
InfoView information related to the Entity.
SaveVisible only when changes have been performed.
Entries editorThe editor where entries and variables can be added in a table-like view
Add entryAllows the user to add a new entry.Add Entries and Variables
Entries
Add string variableEither a string, Language Object, or another Entity.Variables
Add script variableA string or a value obtained from a script.Variables
Generate EntriesUse LLMs to generate Entries using Teneo Copilot.Teneo Copilot
TryoutAllows the user to test changes.Tryout

Practical Examples​

Simple Entity​

This simple Entity contains entries denoting cities in the Netherlands:

nl

To enhance natural understanding, the entries can have variables carrying additional information about each entry. For example, different names may denote the same city, like "Den Haag" and "The Hague". With variables, it is possible to map these different variants to the same city name. Another example is the code of the nearest airport, which is useful to have in flight booking scenarios.

nl

Entity with Language Objects​

This Entity maps Language Objects to strings:

example_entity_lb

Accessing Variables​

One way to access Entity variables is by using Listeners.

Here, the Flow Variable orderedBeverage is assigned lob.beverageType. This lob is a special variable which points to the Entity (or, more generally speaking the Language Object, hence lob) to which the script has been attached to, BEVERAGES_SERVED.ENTITY, and retrieves the value of the Entity's variable beverageType. This way, if a valid beverage type is mentioned in the conversation, it is picked up by the Listener, stored in a Flow Variable and stored for further processing, such as ordering the beverage.

accessing_entity_variables_2

Using Script Variables​

In the following example, the value 'americano' will be assigned to the Flow Variable orderedBeverage if the user input is 'I want an americano'.

What happens is the following:

  1. The user says "I want an americano".
  2. All entries of BEVERAGES_SERVED.ENTITY are searched through to match "americano".
  3. A match is found in the values of the nested Entity COFFEES_SERVED.ENTITY, more specifically in the Language Object AMERICANO.NN.LEX.
  4. The value "americano" of the Entity variable coffeeType is propagated up to the Entity variable beverageType.
  5. The value of the variable beverageType is accessed via the propagation script in the listener condition and assigned to the Flow Variable orderedBeverage.

value_propagation_3

Tips and Tricks​

Automatic Propagation of Variable Values​

Variables of referencing entries can be automatically set to propagate the variable value when a matching variable is present.

  • A new referencing entry is added to the parent - any matching variables will be propagated.
  • A new variable is added to the parent - any referencing entry with matching variables will be propagated.

In this example:

  • CITIES Entity contains a city_code string variable.
  • A new SPECIAL_CITIES Entity / Language Object is added. This has a city_code NLU variable and a three-character value.
  • In the Entity CITIES a reference to the SPECIAL_CITIES Entity / Language Object is added.

The editor now detects the city_code variable in the SPECIAL_CITIES Entity / Language Object and adds the value obtained from lob.city_code to the variable cell. In other words, this is a more automatic way to obtain values for the entries in an Entity.

The value "BAS" is only assigned when Basingstoke is found (as specified in the first row of SPECIAL_CITIES.LOB)

entity-variable-propagation