Teneo Developers

Bulk Import

The Bulk Import feature of Teneo Studio is a longed-for revolution allowing users to create language objects, entities, or Question and Answer (Q and A) pairs outside Teneo Studio and later import them into a solution. With the Bulk Import feature, users of Teneo Studio can import a set of language objects, entities, or Q and A pairs in a quick and simple way, just by browsing for a file and selecting it. The Bulk Import format is flexible and powerful when it comes to adding information directly in the file before importing; for example, it allows users to easily add flow names, answer texts, multiple triggers, positive examples, variables and values, language object conditions, and entity entries with string and/or script variables and values, and it even allows users to specify the folder location.

Build - Bulk Import: bulk-import

Format

Bulk Import works with the csv (comma delimited) file format. These files can for example be created using Excel (or any other compatible format) to later be saved as .csv. Encoding in UTF-8 and UTF-8-BOM is supported.

Importing the file

The Bulk Import button can found in the Solution view in Teneo Studio. It is located in the the Home tab:

Build - Bulk Import: 1-bulk import button big

Warnings and errors

Teneo Studio performs a series of checks to validate the file to be imported; if the validation fails, the import is cancelled, and an error message is displayed, informing the user about the issues encountered in the file.

Build - Bulk Import: 3-errors

When hovering over any of the errors with the mouse, more information related to the encountered error is displayed:

Build - Bulk Import: 4-errors detail

The validation process only verifies the format of the csv file and that all mandatory fields are added correctly; it doesn’t check any other aspect, such as the condition syntax, and it is therefore recommended to always check the condition syntax after an import has finished.

When bulk importing language objects or entities, Teneo Studio will not accept a file containing duplicates, i.e. several language objects with the same name or alias, nor will it accept a file containing language object names or aliases already present in the solution. If a flow name is not unique within a folder, Teneo Studio will rename the imported Q and A pair’s name by adding a number to the end of the it.

Rules

General rules

  • Fields are separated by commas (,) or semi colons (;).
  • Start tags are prefixed with the pound sign (#).
  • New lines/carriage returns/extra delimiters are ignored.
  • The same file cannot mix an import of language objects, entities, and Q and A pairs.
  • Starting a line with the #ignore tag ignores the entire line during the import process. This can be used to write headers or comments in the file.

Quotes

When creating the .csv file with a text editor or similar, double quotes must be escaped with an extra double quote. In addition, the entire field must be double quoted. See examples below.

  • A quoted condition: “Anderson>>””&””>>(co/company)”
  • A string NLU variable value: “””New York”””
  • For string NLU variable values, Groovy also permits single quotes, and they can be added to the .csv file without having to be escaped: ‘New York’

Language object rules

When creating the file to import language objects, each line in the file represents a new language object. The #language_object tag indicates the start of a new language object and is mandatory. The tag can be followed by the fields shown in the following table:

Tag*Field 1*Field 2**Field 3**Field 4*Field 5Field 6
#language_objectnamealiasdescriptionconditionpositive examplesnegative examples

* These fields are mandatory, which means they need to exist in the .csv file and they need to contain values.
** These fields are mandatory, but the values are optional.
The remaining fields are optional. If one or more of these are added, they need to be written in the same line as the #language_object tag they belong to.

The following tags may also be included, but are optional:

Optional tags
#folderfolder name
#nlu_variablesNLU variables nameNLU variables value
#variablesvariables namevariables value

This means that a language object always needs a name and a condition. Alias and description fields are mandatory, but values can be left empty. When adding positive and negative examples to a language object, they need to be specified in field 5 and 6 after the language object tag, but for language objects without positive or negative examples, no fields are needed.

This example imports a language object in its simplest form: #language_object,HAPPY.ADJ.LEX, , ,happy/happier/happiest

The #folder tag is optional, but when used it needs a mandatory field specifying the relative folder path. If the folder doesn’t exist in the solution, it will be created when performing the bulk import. When importing a file into the solution root, the folder tag is mandatory. The optional #variables and #nlu_variables tags are used for adding variables and NLU variables to a language object. Multiple variables can be added by simply adding additional name and value pairs.

Descriptions of tags and fields

NameDescription
#language_objectThis mandatory tag indicates the beginning of a new language object.
NameThe name of the language object. This field is mandatory and must contain a value. The value must be written in capital letters and it must be unique, both within the file and within the solution it is imported to.
AliasThe alias of the language object. This field is mandatory, but the value is optional. If used, the value must be written in capital letters and it must be unique, both within the file and within the solution it is imported to.
DescriptionThe description of the language object. This field is mandatory, but the value is optional.
ConditionThe condition of the language object. This field is mandatory and must contain a value.
Positive examplesPositive examples to add to the language object, separated with / (slash). This field is optional.
Negative examplesNegative examples to add to the language object, separated with / (slash). This field is optional.
#folderThis tag indicates that the following field contains information about the folder path. It is optional unless the file is imported straight into the solution root, in which case the tag and relative folder path are mandatory.
Folder nameThe folder where the import will be stored, relative to current selected folder in Teneo Studio.
#nlu_variablesThis optional tag indicates that at least the two following fields are a name and a value of an NLU variable. It is possible to add multiple name/value pairs.
NLU variables nameThe name of the NLU variable.
NLU variables valueThe value of the NLU variable.
#variablesThis optional tag indicates that at least the two following fields are a name and a value of a language object variable. It is possible to add multiple variable name/value pairs.
Variable nameThe name of the language object variable.
Variable valueThe value of the language object variable.

Entity rules

To Bulk Import entities to a Teneo Studio solution, the file can contain the following tags and fields:

TagField 1Field 2Field 3Field 4
#entity*name*descriptionpositive examplesnegative examples
#string_variablestring variable name
#script_variablescript variable name
#entry*entry value*value of string variablevalue of script variable
#folderfolder name
* These fields are mandatory.

Note the mandatory fields; an entity always needs a name and an entry.

The following is an example of a bulk import file with an entity in its simplest format: #entity,AIRPORTS,#entry,Arlanda

Descriptions of tags and fields

NameDescription
#entityThis mandatory tag indicates the beginning of a new entity.
NameThe name of the entity. This field is mandatory and must contain a value.
#entityThis mandatory tag indicates the beginning of a new entry.
Entry valueThe value of the entry. This field is mandatory and must contain a value.
#string_variableOptional tag indicating a new string variable.
String variable nameOptional field indicating the name of a string variable.
String variable valueOptional field indicating the value of a string variable. Note that the value should follow the entry to which it belongs.
#script_variableOptional tag indicating a new script variable.
Script variable nameOptional field indicating the name of a script variable.
Script variable valueOptional field indicating the value of a script variable. Note that the value should follow the entry to which it belongs.
DescriptionThe description of the language object. This field is mandatory, but the value is optional.
Positive examplesPositive examples to add to the language object, separated with / (slash). This field is optional.
Negative examplesNegative examples to add to the language object, separated with / (slash). This field is optional.
#folderThis tag indicates that the following field contains information about the folder path. It is optional unless the file is imported straight into the solution root, in which case the tag and relative folder path are mandatory.
Folder nameThe folder where the import will be stored, relative to current selected folder in Teneo Studio.

Q and A rules

When performing a Bulk Import of Q and A pairs, Teneo Studio will by default create Machine Learning Class Intent Triggers (Class triggers) unless specific information related to Language Condition Syntax Intent Triggers (Syntax triggers) is provided, this means that if the user wish to create a flow with one or more Syntax triggers, the order group or condition should be specified, while the Class Name should be left empty.

To import flows of the type Question and Answer pairs, the .csv file needs to contain the below fields, in the specified order:

TagField 1Field 2Field 3Field 4Field 5Field 6
#question_answer*flow name*descriptionoutput urlrandom answer order (true|false)
#question*trigger name**positive examples**negative examplesorder groupconditionclass name
#answer*answer*emotion
#folderfolder name
* These fields are mandatory.
** These fields are mandatory but can be left without values.

Note: to specify the last optional field, the preceding fields must be specified too, even if they are left empty. For example, to specify only a class name after a question tag, we might use something like the following example: #question, , , , , ,MY_CLASS_NAME

Descriptions of tags and fields

NameDescription
#question_answerThis tag indicates the beginning of a new flow (Q and A pair) and is mandatory.
Flow nameThe name of the flow that will be generated once the Q and A file is imported. This field is mandatory and requires a value.
DescriptionThe description of the flow that will appear on the Properties tab. This field is optional.
Output URLThe output hyperlink to be showed in the answer. This field is optional.
Random answer orderOptional field to choose whether the answer order is random or not, by adding the Boolean value true/false.
#questionThe question tag indicates the start of a new trigger. Every Q and A pair requires at least one question tag with its mandatory field. Multiple triggers can be added to a flow with additional question tags.
Trigger nameThe name of the trigger. This field is mandatory, but its value is optional.
Positive examplesPositive examples, separated with / (slash) to be added to the trigger. This field is mandatory, but its value is optional.
Negative examplesA list of negative examples, separated with / (slash) to be added to the trigger. This field is optional.
Order groupThis optional field specifies an order group for the trigger. If no order group is specified, triggers will be added to a “Q and A’s” ordering group which is automatically added to the Intent Ordering during Bulk Import.
ConditionThis field is optional and can be used to add a fixed condition for the trigger. If no condition is added, the condition will be auto generated based on the positive examples (and negative examples if applicable).
Class nameThis field is optional and can be used to specify the Class Name of a Class Match Requirement. Please note that the Class Name needs to be upper case and cannot contain any spaces.
#answerThis mandatory tag indicates a new answer. Multiple answers can be added to a flow with additional answer tags. Multiple answers end up in the same output node and their order can be set to fixed or random in the RANDOM ANSWER ORDER (see above).
AnswerThis mandatory field is for the answer text and it must contain a value.
EmotionThe name of the emotion for the answer. This field is optional, but if used, the named emotion must already exist in the solution for it to be added.
#folderThis tag indicates that the following field contains information about the folder path. It is optional unless the file is imported straight into the solution root, in which case the tag and relative folder path are mandatory.
Folder nameThe folder where the import will be stored, relative to current folder selection within Teneo Studio.