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.
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:
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.
When hovering over any of the errors with the mouse, more information related to the encountered error is displayed:
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.
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 5 | Field 6 |
|---|---|---|---|---|---|---|
| #language_object | name | alias | description | condition | positive examples | negative 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 | ||
|---|---|---|
| #folder | folder name | |
| #nlu_variables | NLU variables name | NLU variables value |
| #variables | variables name | variables 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
| Name | Description |
|---|---|
| #language_object | This mandatory tag indicates the beginning of a new language object. |
| Name | The 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. |
| Alias | The 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. |
| Description | The description of the language object. This field is mandatory, but the value is optional. |
| Condition | The condition of the language object. This field is mandatory and must contain a value. |
| Positive examples | Positive examples to add to the language object, separated with / (slash). This field is optional. |
| Negative examples | Negative examples to add to the language object, separated with / (slash). This field is optional. |
| #folder | This 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 name | The folder where the import will be stored, relative to current selected folder in Teneo Studio. |
| #nlu_variables | This 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 name | The name of the NLU variable. |
| NLU variables value | The value of the NLU variable. |
| #variables | This 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 name | The name of the language object variable. |
| Variable value | The 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:
| Tag | Field 1 | Field 2 | Field 3 | Field 4 |
|---|---|---|---|---|
| #entity* | name* | description | positive examples | negative examples |
| #string_variable | string variable name | |||
| #script_variable | script variable name | |||
| #entry* | entry value* | value of string variable | value of script variable | |
| #folder | folder name | |||
| * These fields are mandatory. |
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
| Name | Description |
|---|---|
| #entity | This mandatory tag indicates the beginning of a new entity. |
| Name | The name of the entity. This field is mandatory and must contain a value. |
| #entity | This mandatory tag indicates the beginning of a new entry. |
| Entry value | The value of the entry. This field is mandatory and must contain a value. |
| #string_variable | Optional tag indicating a new string variable. |
| String variable name | Optional field indicating the name of a string variable. |
| String variable value | Optional field indicating the value of a string variable. Note that the value should follow the entry to which it belongs. |
| #script_variable | Optional tag indicating a new script variable. |
| Script variable name | Optional field indicating the name of a script variable. |
| Script variable value | Optional field indicating the value of a script variable. Note that the value should follow the entry to which it belongs. |
| Description | The description of the language object. This field is mandatory, but the value is optional. |
| Positive examples | Positive examples to add to the language object, separated with / (slash). This field is optional. |
| Negative examples | Negative examples to add to the language object, separated with / (slash). This field is optional. |
| #folder | This 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 name | The 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:
| Tag | Field 1 | Field 2 | Field 3 | Field 4 | Field 5 | Field 6 |
|---|---|---|---|---|---|---|
| #question_answer* | flow name* | description | output url | random answer order (true|false) | ||
| #question* | trigger name** | positive examples** | negative examples | order group | condition | class name |
| #answer* | answer* | emotion | ||||
| #folder | folder 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
| Name | Description |
|---|---|
| #question_answer | This tag indicates the beginning of a new flow (Q and A pair) and is mandatory. |
| Flow name | The name of the flow that will be generated once the Q and A file is imported. This field is mandatory and requires a value. |
| Description | The description of the flow that will appear on the Properties tab. This field is optional. |
| Output URL | The output hyperlink to be showed in the answer. This field is optional. |
| Random answer order | Optional field to choose whether the answer order is random or not, by adding the Boolean value true/false. |
| #question | The 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 name | The name of the trigger. This field is mandatory, but its value is optional. |
| Positive examples | Positive examples, separated with / (slash) to be added to the trigger. This field is mandatory, but its value is optional. |
| Negative examples | A list of negative examples, separated with / (slash) to be added to the trigger. This field is optional. |
| Order group | This 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. |
| Condition | This field is optional and can be used to add a fixed condition for the trigger. If no condition is added and no Class name is specified, the trigger will be marked as TODO. |
| Class name | This 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. |
| #answer | This 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). |
| Answer | This mandatory field is for the answer text and it must contain a value. |
| Emotion | The 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. |
| #folder | This 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 name | The folder where the import will be stored, relative to current folder selection within Teneo Studio. |