Localization structure

Currently the options and functionalities described in this page apply only toTeneo Studio Desktop

Create a Master solution

Creating a Master solution is as easy as creating any other new solution in Teneo Studio, see how to do this here.
Any existing solution can also be converted into a Master solution by first selecting the documents to share (see below section) and then by branching a new solution under it, please see how to branch a solution here.

Select documents to include

In any solution created prior to the Teneo 6 release, and upgraded or imported to Teneo 6, all documents are per default set to be included.

When creating new documents in a solution (both in a new and imported/upgraded solution) however, documents are per default set as not included.
In both scenarios, it is highly recommended to review and select which folders and documents to include in the Local solution(s) before performing the branching of the new Master solution.
In the existing (Master) solution, documents can be excluded and included by simply clicking the Exclude/Include buttons available in the top ribbon (Branching area) of the Flow, Language Object, Entity, etc.

Global documents, in the backstage of Teneo Studio (Solutions tab > Globals), have the option to Include or Exclude the documents available in the top of the view.

In the Solution Explorer view of Teneo Studio it is possible to multi-select various documents and click either the Include or Exclude button in the top ribbon of Teneo Studio to include/exclude various documents at the same time.

When a folder is selected to include/exclude, Teneo Studio prompts the user to select if the inclusion/exclusion applies to the selected folder and its content only or also to any sub-folders and their content.

It is possible to multi-select documents for inclusion/exclusion for the following documents: Classes, Emotions, Global Listeners, Global Variables, Integrations, Scripted Contexts, Flows, Language Objects, and Entities.

For an overview of the properties' behavior in a Localization setup, please see the List of Localization setups properties.

Create a Local solution

When the documents to share have been selected in the Master solution, close the solution and go to the Solutions tab of Teneo Studio (no solution open). The Local solution is created by following the below steps:

Select the existing solution which should be the Master solution
Click the Branch button in the top of the view

The Branch Solution window will open
Select the Language of the Local solution
Confirm the Solution Content:
- Master and Template
- Master and Imported File
- Master only
Give the Local solution a Name, optionally Add a description
Click OK

A pop-up message informs the user that the branching has begun and a progress bar is displayed while the branching is taking place in the Solutions list.

Solution Content

When branching a Master solution, the following options for Solution Content in the Local solution are available:

Master and Template: the Local solution will be created with the content from the Master solution plus the content of the selected template; a template is usually a Teneo Dialogue Resource but can be another solution available in the environment for the selected language
Master and Imported File: the Local solution will be created with the content from the Master solution plus the content of the imported .solution file (a previously exported Teneo solution)
Master only: the Local solution will be created containing only the content from the Master solution.

When selecting Master and Template or Master and Imported File as Solution Content, please also see the Document behavior section further below .

Result

When the branching process is complete, any Local solutions are grouped under the Master solution in the Solutions list.

The Local solution(s) created is a new solution where the selected documents from the Master solution are inherited; the Local solution therefore contains documents where some properties are Master-controlled and hence not editable in the Local solution.

Of course, any language specific properties, such as TLML syntaxes, assigned Lexical Resources (e.g., Teneo Lexical Resources), additional Language Objects and Entities can be edited in the Local solution; more documents can also be added in the Local solution without these having to exist in the Master solution as well as the Local solution can contain, for example, a Teneo Dialogue Resource without it being inherited or shared from the Master solution.

For specifics about the the behavior of the various properties, please see the Localization setups Properties lists

Visualization of Master-controlled documents

Master solution

In a Master solution, the documents which are shared with one or more Local solutions are displayed with a down-arrow icon to inform the user of the Master-controlled content.

Folders can be displayed with two different icons depending if the folder and all the content included is being shared or if the folder and only some or none of the content is shared.

Local solution

In the Local solution, the documents which are Master-controlled, are displayed with a shield to emphasize the documents relation to the Master solution.

Note also that Order groups coming from the Master solution are visualized with the shield to emphasize that the document is connected to the Master solution. Read more about ordering in Localization setups here.

My work tab

Once changes have been made and saved in the Master solution of documents shared with Local solution(s), these updates are displayed in the Local solution(s) as Master Solution Changes in the My Work tab in the backstage of Teneo Studio (Solution tab > My Work).

The user can choose between updating All X items or Selected by using the buttons available at the top. Note that the user is prompted to confirm the update of documents when the button is clicked.

The Flows, Entities, and Language Objects with pending updates can also be updated from within the document, when the document already exists in the Local solution.

It is also possible to Open the Master document before applying the update in order to see what has changed.

When applying an update, the system will copy all the appropriate changes from the Master document to the Local document. Read more about Updates from the Master.

Order groups

Order groups added in the Master solutions are - from Teneo 6 - always added as an update in the Local solution.

Accepting the update will add the Order group to the Local solution at the bottom of the list of Order groups, regardless of what position it had in the Master solution.

An Order group connected to the Master solution will have a shield to help the user distinguish between Local Order groups and Order groups coming from the Master solution.

The ordering itself and any properties of an Order group, such as its name and the Intent Triggers contained in it remains fully Local-controlled and such changes in the Master solution will not result in updates in the Local solution(s).

When a Local solution is presented with Flow updates that contain new Intent Triggers belonging to a non-existing Order group in the Local solution, the application of the Flow updates will automatically apply the Order group updates and assign the new Intent Trigger to the same Order group in the Local solution.

Delete Master-controlled documents

Folders

When a Local solution receives an update to delete a Master-controlled folder, any local documents (i.e., not Master-controlled) in the Master-controlled folder will not be deleted, and the folder itself will not be deleted either but rather unlinked from the Master solution.

Deleting a Master-controlled folder and its content will result in an unlink update for the folder and delete updates for the documents in the Local solution. Applying only the unlink update will also apply the delete of the documents, because an unlinked folder can't have Master-controlled documents inside.

It is possible to link back a folder by simply restoring it from the Recycle Bin in the Master solution and applying the link update in the Local solution.

Because of how the Recycle Bin works if, for example, in Master a Flow is restored and its original location doesn't exist anymore, the folder structure will be recreated. This means that the Local solution will have a restore from Recycle Bin update for the Flow and an add update for the created folders in Master.

Classes

When a class is deleted in the Master solution, the Local solution will receive an unlink update; when applying the update, the class in the Local solution will be unlinked from the class in the Master solution.

To link back a class, the class should be restored from the Recycle Bin in the Master solution, and the link update applied in the Local solution.

Detach Flows

In the case of Flows, Local users can decide that what the Master has provided does not meet their needs and an option to Detach the Flow from the Master solution is available in the top ribbon of the Flow.

When detaching a Flow, the link to the Master solution is broken. The user will be able to modify any property of the Flow, including the Flow structure, but no more updates from the Master solution will be provided.

To undo a detach action right after clicking the Detach button, simply click Undo in the Flow's top ribbon. To undo a detach action after saving and closing the Flow is only possible by rolling back to a version where the Flow was linked to the Master Flow.

This is done by going to the Flow's backstage (Flow tab) and selecting History in the left side panel. In the History view, open a version which was linked to the Master by clicking the version number. In the window of the previous version of the Flow, click the Restore button. The Flow is now restored to the selected version and linked to Master.

Reset document

It is possible to reset Local documents to Master, doing this implies that any local changes to the document will be overwritten by the current version of the document in the Master solution.

Pause branching

If a document first is set to include (and branched to at least one Local solution) and later on is set to exclude, it means it is paused from branching, and it will still remain in the Local solution(s). Branching will start again if the document is again included.

This allows users to temporary pause updates for a document while expanding/changing/testing it, for example.

If the first-included-later-excluded document is deleted in the Master solution, it is also deleted from the Local solution(s).

Copy of documents

Note that when Folders, Flows, Entities or Language Objects are copied within a solution, or copied from other solutions, the copied version will automatically be set to Exclude from branching and the user will need to manually include the document in case the document should be propagated to Local solutions.

Copy Local Flow to Master

If a Flow is created in the Local solution which is later found to be needed in the Master solution, the user can - with the Master solution open - use the advanced Search functionality of Teneo Studio to find the Local Flow and copy it over to the Master solution.

Note that this will create a copy of the original Local flow in the Master solution which can then be set to include in the Localization setup. Furthermore, it is recommended to delete the original Flow from the Local solution before applying the Add-update of the copied Flow from the Master solution in the Local solution.

Import

At the time of branching of a Master solution, Teneo Studio provides the two following options to import additional content to the Local solution:

Master and Template
Master and Imported File

For an already existing Local solution, the below option is available to import additional content:

Add Content (available in the backstage of the Local solution: Solution tab > Import/Export > Add Content)

Before performing any type of import to a Local solution, it is recommended to read carefully the section Document behavior available further below.

Export and Import of Localization structure

It is possible to export and import an already existing Localization structure, i.e., solutions where the Master and the Local documents have identical Ids; see the below Document behavior section for information related to the handling of documents when merging solutions.

It isstrongly advised to apply any pending updates in Local solutions before exporting the Localization structure to be able to keep track of these

To export and import a Localization structure, follow the below steps:

Recommendation: In the Local solution(s) apply any pending updates
Export the solutions as described here
Next, import the Master solution as a new solution (for guidance, see here)
When this is done, Branch the Master solution
Select the Language of the Local solution
Select Master and Imported File for the Solution Content
Click Browse to select the .solution file
Back in the Branch Solution window, click Next
Give the Local solution a Name and optionally add a Description
Lastly, click OK to start creating the solution.

Document behavior

When performing a Branch action with either Master and Template or Master and Imported File to create a new Local solution or when Adding Content to an existing Local solution, bear in mind the following behavior:

"Imported Solution(s)" in the below bullet points refers to any files imported, be this template solutions or imported files at the time of branching or a .solution file imported by using the Add Content function

Intent and Prompt Trigger Ordering
- Order groups from the imported solution are placed at the top of the Trigger Ordering, i.e., above the Order groups from the Master solution. The internal order from each solution is kept.
- The Default Order group in the imported solution becomes the Default group in the Local solution
- Due to the two above points it is highly recommended to review and if necessary adapt the Trigger Ordering once an import has finished
File Resources
- Only File Resources from the imported solution are added to the Local Solution, i.e., no File Resources from the Master solution are added
Metadata
- Metadata is fully Master-controlled, therefore any Metadata in the imported solution is ignored
Solution Properties
- On branching with either template or imported file, the Solution Properties for Location, Quality Control, Confidence Threshold and Notes in the new Local solution will be the ones coming from the template/imported file (these properties are locally controlled as described here)
- When adding content to an existing Local Solution, the Solution Properties are not updated with new values (as these might have been already adjusted in the Local solution).