Import and export coaching TML

You can now migrate coaching from one Model to another across different Orgs and instances or clusters using the coaching TML file. This feature allows you to transfer coaching insights efficiently, eliminating the need to duplicate efforts in training Spotter for each Model or Worksheet separately. To export or import coaching, you must have edit access to the respective Model or Worksheet.

Migration target scenarios

The three main factors to consider in migrating Spotter coaching are:

Target and source environments.
Number of targets.
Target Worksheet/Model differences.

Target and source environments

Across different clusters

A common scenario where analysts test Spotter on a Worksheet in a development environment and, once satisfied with the training, replicate this to the production environment for business users. This applies to both TSA (Cloud) and TSE (Embedded) customers.

Within the same cluster or environment

Users often migrate training from one Worksheet to another within the same cluster.

Use Cases:

TSE customers might have a primary Worksheet and want to replicate training across Worksheets dedicated to different end clients separated by user groups within the same environment.
Customers might be creating a reduced version of a Worksheet to enable Spotter when the existing use case is too difficult to train in one session.
Customers might have identical Worksheets in a cluster and want to train on all of them in one session.

Across different Orgs

TSE customers often operate multiple Orgs within a cluster and need to migrate training from one Worksheet in a primary Org to Worksheets in other Orgs.

Number of targets

From one source Worksheet to a single target Worksheet

Typically, customers migrate training from a development Worksheet to production to ensure consistency for business users. This process is straightforward, focusing on one-to-one replication.

From one source Worksheet to multiple target Worksheets

Training across multiple Worksheets in one cluster in one session:

Customers aim to avoid duplicating training efforts on similar Worksheets.
For instance, one company wants to train on multiple identical Worksheets (only differing by data rows). Another company also wanted to train on the table level since most of the Worksheets were derived from one base table.
In the current scenario, this can only be addressed efficiently through migration, where training is performed on one Worksheet and then migrated to others.

Replicating experience for multiple customers

TSE customers often need to migrate training data to Worksheets for each of their end clients to provide a consistent experience across their client base.

Target Worksheet differences

Customers want to replicate the Spotter experience from one Worksheet to another. However, depending upon the difference between the two Worksheets, there could be challenges in migration or replicating the experience.

Identical Worksheet

Target Worksheets are direct copies of the original Worksheet, sharing the same data columns.
Migration in this case ensures consistency and allows for seamless replication of the training without any adjustments.

Slightly different Worksheet

Target Worksheets may differ from the source Worksheet:

Contain additional or fewer columns.
Have the same columns with modified names.

While the underlying table joins might stay consistent, TSE customers often adjust Worksheets according to their clients' data. Adaptations are necessary to maintain the relevance and effectiveness of training during migration.

Export coaching from a Model or Worksheet

You can export coaching TML files from the Model or Worksheet view in the Data workspace by following these steps:

Navigate to the Data workspace and select the Model or Worksheet containing the coaching you want to export.
Select the more options icon and hover over the TML section.
If you select Export TML:
- Select Export Model/worksheet and Export associated Spotter coaching to download the Model/Worksheet TML file and coaching TML file. Click Save.
- Alternatively, select Export Model/worksheet & associated objects (tables etc.) and Export associated Spotter coaching to download the TML files for the Model or Worksheet, all upstream objects, and the coaching. Click Save.
If you select Export coaching TML:
- Select Export Spotter coaching only to download only the TML file containing all coaching objects. Click Save.
- Select Export Spotter coaching & associated objects (models etc.) to download the TML files for the Worksheet/Model, all upstream objects, and the coaching. Click Save.

No coaching file is created if there are no coaching entries associated with the Model/Worksheet.

Export coaching from Coach Spotter

You can export coaching from the Spotter coaching pages in the Data workspace. To export coaching from the Spotter coaching pages, follow these steps:

Navigate to the Data workspace and select Reference questions or Business terms from the left menu.
Select the checkboxes next to the questions or terms for which you want to export a TML file. Below the Spotter heading, the following three options appear:
- Change access
- Delete
- Export
Select Export. The TML file automatically downloads.

Export coaching using ThoughtSpot Embedded APIs

You can download coaching TMLs from ThoughtSpot Embedded APIs as long as you are using v2. The specific API is /api/rest/2.0/metadata/tml/export.

To export only the TML of coaching associated with an object, set the GUID of the object as identifier and set the type as FEEDBACK in the metadata array.

To export the TML of an object along with the coaching associated with it, set the GUID of the object as identifier, set the type as LOGICAL_TABLE in the metadata array, and set export_with_associated_feedbacks in export_options to true.

We also support custom object IDs in coaching TML files.

Custom object IDs are in beta and off by default. To enable them, contact ThoughtSpot Support.

Import coaching into ThoughtSpot

Import into a Model or Worksheet

To import a coaching TML file directly into a Model or Worksheet, follow these steps:

Navigate to the Data workspace and open the Model or Worksheet you want to import TML coaching into.
Select the more options icon and hover over the TML section.
Select Import coaching TML.
The Import coaching page appears. Click Select .tml file to upload to search your files and upload the TML file, or drag and drop it. Ensure that the file is in .tml format.

Ensure that the GUID in the coaching TML matches the target Worksheet or Model GUID.
The Import screen appears, showing the object name, file name, status, and possible actions. You can select Edit to edit the TML file. When ready, select the checkbox next to the file or files and click Import n selected.
Click Exit. The coaching will be appended to the Worksheet or Model’s coaching TML file.

Mandatory fields

Attribute	Reference question	Business term
access	Mandatory.	Mandatory.
axis_config	Mandatory.	Optional.
axis_config	Mandatory.	Optional.
chart_type	Mandatory.	Optional.
feedback_phrase	Mandatory.	Mandatory.
id	Mandatory.	Mandatory.
parent_questions	Optional.	Mandatory.
rating	Mandatory.	Mandatory.
search_tokens	Mandatory.	Mandatory.
type	Mandatory.	Mandatory.

Attribute

Reference question

Business term

access

Mandatory.

axis_config

Mandatory.

Optional.

axis_config

Mandatory.

Optional.

chart_type

Mandatory.

Optional.

feedback_phrase

Mandatory.

parent_questions

Optional.

Mandatory.

rating

Mandatory.

search_tokens

Mandatory.

type

Mandatory.

Resolving errors

To avoid errors with coaching TML files, check the following before uploading:

Check that the GUID present at the top of the file is a valid Worksheet or Model already present in the system.

We do not currently support importing a new Worksheet and its coaching in the same zip file.
Check the sanity of the TML file, making sure you don’t have missing fields, invalid entries for fields like type, access, chart_type, or display_mode, invalid search_tokens for the Worksheet or Model, or invalid formula expressions for the Worksheet or Model that coaching entries are being targeted for.
Check for similar entries within the file: No two coaching entries can have the same 'feedback_phrase'. This can occur when uploading coaching entries on the user level, which can have the same coaching phrase. The system will throw an error when uploading multiple such entries. Users have the option to edit the coaching TML to avoid such scenarios.
Check for conflicts with existing entries: The coaching entry should not have the same 'feedback_phrase' as a coaching present already on the target Worksheet. It will throw a warning and will override the existing coaching entry if import is still done. Users have the option to edit the coaching TML or modify the existing entries to avoid the conflict.
Do not modify the values for the following fields: display_mode, chart_type, and axis_config. Changes to these fields are not validated by the system during upload and may lead to unintended behavior.

Related information

TML for Spotter coaching