Teneo Developers

Entity Basics

Introduction

Entities allows to create linguistic building blocks containing smaller or larger collections of entries to identify values and optionally extract relevant data from the user inputs via Variables; Entities

Available Entities

From a solution, users have access to the following collection of Entities:

  • Entities located in the solution, and
  • Entities available in any lexical resource assigned to the solution

Entities located 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 lexical resource (e.g. Teneo Lexical Resources) can be viewed and used in TLML Syntaxes but not modified.

Naming an Entity

When naming Entities, bear in mind that:

  • the name must be unique within the solution
  • the name is 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 underscore by Teneo If an Entity in the solution shares its name with an Entity in an assigned lexical resource, the Entity located in the solution is always chosen by Engine over the Entity in the assigned lexical resource.

Entries editor

An entry is one row in the table view (or Entries editor) and the entry value can consist of plain text or a reference to either a single Language Object or a single Entity. Each entry value can have zero, one or more variables attached in the following columns. The entry value needs to be unique within the Entity and Teneo Studio will prevent the user from saving the Entity if two entry values are the same.

To use an Entity as an entry or in the Syntax editor, its name must be preceded by the percentage sign (%) and written in capitalized letters; Teneo Studio will automatically capitalize letters written after the percentage sign.

Note that the Longest Match option (:L) is implicitly applied to the Entity.

Read more

Open

To open an Entity in read only mode, either:

  • Double-click the wanted Entity in the Solution Explorer view
  • Select the Entity and click Open in the top menu
  • Right-click the Entity and select Open in the context menu

Activate edit in the opened Entity by clicking Edit in the top ribbon of the Entity

To open an Entity in edit mode, either:

  • Press the Alt key while double-clicking the wanted Entity in the Solution Explorer view
  • Select the Entity and click Edit in the top ribbon
  • Right-click the Entity and select Edit in the context menu

Open a referenced Language Object or Entity from the Entries editor by left-clicking and selecting Open (opens in read-only mode) or Edit (opens in edit-mode).
Open a referenced Entity from the Syntax editor by either double-clicking the name (opens in read-only mode) or by pressing Alt while clicking to open in edit mode.

Note that Language Objects and Entities referenced from an assigned lexical resource always open in read-only mode.

Open an existing Entity by:

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

Create

To create a new Entity, simply follow the below steps:

  • Go to the Solution Explorer in the main Teneo Studio window (Home tab)
  • Optionally select the folder, or create a new folder, where the Entity should be added
  • In the top ribbon, click on the Entity button in the New area
  • the Entity window opens on the Properties tab, add the Name of the Entity Note that the .ENTITY suffix is automatically added to the Name field
  • Optionally, add a Description
  • Click the green Play icon, or the back arrow in the top left corner
  • Enter the Entries and any wanted Variables and Values
  • Optionally add Examples in the right side panel
  • Remember to Save to preserve all the modifications.

Need to create several Entities (or Language Objects)? Consider using Bulk Import

Create Entity from the Entity editor

Create a new Entity (or Language Object) from the Entity editor by right-clicking the strikethrough reference to the new document and select Create Entity or Create Language Object in the context menu

Right-click to Create

Bulk data creation

Data can be added to an Entity in bulk by dragging/dropping or copying/pasting content from external files. The data can be single piece of text (no TABs and a maximum of one trailing carriage-return) which when pasting will enter the text in all the selected cells, or an array of data with 1-n rows and 1-n columns. Pasting or drag-dropping will create new entries.

Please note:

  • Rows are carriage-return separated
  • Columns are TAB separated
  • Variable columns are only created if they are needed when using drag/drop or copy/paste
  • When creating new variable columns, the user can decide if first row in the pasted data should be header, i.e. variable names or just data
  • If the Entity already has enough variables defined, then no variable columns are created
  • Variable columns created when using drag/drop or copy/paste defaults to the type string
  • If one or more of the variables to be pasted should be of the type scripts, to avoid them becoming string types when pasted (and thus resulting in quoted scripts if the type is changed), rather:
    • Copy and paste the header, i.e. the variable names only, this will just create the variable columns
      • Remember to include an empty entry column in the one-row of data to copy
      • Change the type of the variables that are to be script types
      • Now, copy and paste the entries data.
  • When using Ctrl + c on more than one row, the Ctrl + v shortcut will paste into the first column as entries
  • When using Ctrl + c on one field and marking several rows, doing Ctrl + v will paste to several rows the same content.

To create a new Entity, follow the below steps:

  • Optionally, navigate to the folder where the Entity should be created
  • In the lower, right corner of the browser window, click the Create (New Document) button and select Create New Entity

Create New Entity

  • The Create New Entity opens, write the Entity name and, optionally, an Entity description
  • Lastly, click Create Entity

Edit

After opening the Entity in edit mode, the user is able to work on the Entity below please find an overview of the available options.

Entity: top ribbon (Home tab)

Top ribbon

The Entity top ribbon provides a range of buttons and options for working with the Entity, in the below table the different buttons are listed and - when relevant - links to more information provided.

SectionButtonCommentMore info
EntityCloseClose the Entity window
SaveSave the Entity in the current state; clicking the lower part of the button allows the user to save the Entity with or without a comment
Enable/disableEnable or disable the EntityEnable or Disable documents
EditUndo/RedoUndo/redo changes performed in the Entity
EntriesAdd EntryAdds new entry line to the Entity
DeleteDeletes the selected entry line
VariablesAdd VariableAdds a new variable
DeleteDeletes the selected variable
String/ScriptSelect if the variable should be of type string or script
Stable VersionSet/UnsetSet the current version of the Entity as stable or unset itVersion flag
BranchingInclude/ExcludeInclude or Exclude the Entity from branching when working in a Localization setupLocalization setup

Entity tab

The backstage of an Entity (Entity tab in the top of the Entity window) contains the below mentioned menu items.

Menu itemCommentMore information
PropertiesAllows to edit the name of the Entity, add a description or view the Id and location
HistoryLists the history of versions created each time the Entity was saved, comments added at save are displayed hereOpen a previous version by clicking the version number; restore a previous version by opening a specific version and clicking Restore in the top ribbonVersion history

After opening the Entity, the following options are available:

  • Search Entry allows to search for a specific entry in the Entry editor
  • Add Entry adds a new entry (at the bottom of the Entry column)
  • Add String Variable; read more
  • Add Script Variable; read more

Updating the name of the Entity is done by clicking the name and performing any needed modification inline.

Read more about the Entries editor here

Save

To save an Entity with a comment follow the below steps:

  • Click Save in the top ribbon of the Entity
  • In the dialogue box (optionally) write a comment
  • Click OK

To save directly and bypass the comment, press the Alt key while clicking the Save button.

To save an Entity, follow the below steps:

  • Click Save in the top right corner of the window Note that the Save button is only visible when changes have been performed
  • Optionally, add a comment
  • 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

To close an Entity, either:

  • Click the X in the top, right corner of the Entity window
  • Click the Close button available in the top ribbon
  • In the Entity backstage, click Close in the left-side menu

Should there be unsaved changes, Teneo Studio prompts the user to Save or Close without saving.

To close an Entity in Teneo Studio Web:

  • First, remember to Save if any changes were performed in the Entity to preserve these; Teneo Studio will prompt the user to save if unsaved changes are detected
  • Next, simply navigate back by using the back arrow of the browser.

Delete

To delete a Entity from the solution, follow the below steps:

  • Select the Entity in the Solution Explorer
  • In the top ribbon of Teneo Studio, click Delete
  • A confirmation message will be displayed, click Delete again If the Entity is in use, an Item in Use message will appear, click Select All to delete anyhow or Continue to cancel deletion (the user can also click the X in the box to cancel the deletion).

For more information, please see Delete documents.

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

  • Navigate to the folder where the Entity is saved
  • Hovering over the Entity, an icon of a recycle bin appears in the right side of the browser window, click it
  • 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

Note that 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.