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
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.
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 .
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
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.
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 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.
Read more about Ordering.
Delete Master-controlled documents
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.
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.
Other document types
Deleting a document in Master will result in a delete update for the Local solution and when applied the document will be sent to the Recycle Bin.
Restoring a document from the Recycle Bin in Master will result in a restore from the Recycle Bin in the Local solution.
In Local, in order to restore from the Recycle Bin a Master-controlled document, the document must first be restored in the Master solution and then the restore from Recycle Bin update can be applied in the Local solution.
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.
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.
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.
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.
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.
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 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).