TML for Monitor alerts

Use TML to modify a ThoughtSpot object in a flat-file format. Then, migrate the object to a different cluster, or restore it to the same cluster.

To work with TML files for Monitor alerts, you can download these objects to flat files in .TML format, modify the files, and subsequently upload the files either to the same cluster, or to a different cluster. To learn how to export, change, and update Monitor alerts, see Import and export TML files.

The syntax examples in this article contain every possible parameter in TML files for Monitor alerts. Some of these parameters are not in these files by default. If you want to use them, you must add them yourself. For example, the fqn parameter is not present in any TML file by default, but you can add it to differentiate a table from another table with the same name.

As you work with TML files, keep in mind that changing elements of the TML file, such as the name of a column or table, may affect dependents. This is specifically true if you are editing TML files outside ThoughtSpot. When you change the name of a table in a TML file, and then import that file into ThoughtSpot, ThoughtSpot automatically updates that table name in any dependents, such as Answers that use the table as a data source. However, if you download multiple TML files from one ThoughtSpot cluster, then change the table name in TML, and upload all the files to a brand-new cluster, ThoughtSpot doesn’t know that the dependents should use that table. You must also change the table name in the dependents.

Syntax of the Monitor alert TML file

The TML file for Monitor alerts has a specific syntax. The Alerts.tml file only appears when you export an Answer or Liveboard and its associated objects.

The Alerts.tml file defines the KPI Monitor alerts associated with the object. If you have administrator privileges, you see every alert for the object. Otherwise, you see only the alerts you created.

See the TML parameters for Monitor alerts for details about the keywords used in this example.

See Limitations of working with TML files for more information about actions you can’t perform using TML.

You may not see each of these parameters in your own TML files, depending on whether each variable is explicitly defined. For example, for scheduled alerts, the condition parameter does not appear. The condition parameter only appears for threshold alerts. You can add that section to the TML file to change a Monitor alert to a threshold alert.

To reduce ambiguity, you may need to add the optional fqn parameter to your TML file when you reference source tables. This is necessary if you have multiple tables with the same name. If you do not add the fqn parameter, and the table you reference does not have a unique name, the file import fails.

We rebranded Pinboards to Liveboards. However, some of the parameters in the alerts.tml file still use Pinboard, not Liveboard. Ensure that you use the correct syntax.

monitor_alert:
- guid: <alert_1_guid>
  name: <alert_1_name>
  frequency_spec:
    cron:
      second: <alert_1_time_seconds>>
      minute: <alert_1_time_minutes>>
      hour: <alert_1_time_hours>>
      day_of_month: <alert_1_day_of_month>>
      month: <alert_1_month>>
      day_of_week: <alert_1_day_of_week>>
    time_zone: <alert_1_timezone>
    start_time: <alert_1_start_time>
    end_time: <alert_1_end_time>
    frequency_granularity: <alert_1_frequency>
  creator:
    username: <alert_1_creator_username>
    user_email: <alert_1_creator_email>
  condition:
    simple_condition:
      comparator: <alert_1_condition_operator>>
      threshold:
        value: <alert_1_threshold_value>
  metric_id:
    answer_id: <alert_1_answer_id>
    OR
    pinboard_viz_id:
      pinboard_id: <alert_1_liveboard_guid>
      viz_id: <alert_1_vizualization_guid>
    personalised_view_id: <alert_1_personalised_view_id>
  subscribed_user:
  - username: <alert_1_subscribed_user_1_username>
  - user_email: <alert_1_subscribed_user_1_email>
  - username: <alert_1_subscribed_user_2_username>
  - user_email: <alert_1_subscribed_user_2_email>
personalised_view_info:
    tables:
      - id: <optiona_table_id>
        name: <table_name_1>
        fqn: <optional_GUID_of_table_name>
    filters:
      - column:
         - <table_name>::<column_name>
        oper: <filter_operator>
        values: <filtered_values>
        - value 1
        - value 2
        - value n
        is_mandatory: [ false | true ]
        is_single_value: [ false | true ]
        display_name: ""
      - column:
        - <table_name>::<column_name>
        is_mandatory: [ false | true ]
        date_filter:
          type: EXACT_DATE_RANGE
          oper: between
          date_range:
            start_date: <start_date>
            end_date: <end_date>
        display_name: ""
- guid: <alert_2_guid>
  name: <alert_2_name>
  frequency_spec:
    cron:
      second: <alert_2_time_seconds>>
      minute: <alert_2_time_minutes>>
      hour: <alert_2_time_hours>>
      day_of_month: <alert_2_day_of_month>>
      month: <alert_2_month>>
      day_of_week: <alert_2_day_of_week>>
    time_zone: <alert_2_timezone>
    start_time: <alert_2_start_time>
    end_time: <alert_2_end_time>
    frequency_granularity: <alert_2_frequency>
  creator:
    username: <alert_2_creator_username>
    user_email: <alert_2_creator_email>
  condition:
    percentage_change_condition:
      comparator: <alert_2_condition_operator>>
      threshold:
        value: <alert_2_threshold_value>
 metric_id:
    answer_id: <alert_2_answer_id>
    OR
    pinboard_viz_id:
      pinboard_id: <alert_1_liveboard_guid>
      viz_id: <alert_1_vizualization_guid>
  subscribed_user:
  - username: <alert_1_subscribed_user_username>
  - user_email: <alert_1_subscribed_user_email>

TML parameters for Monitor alerts

These parameters and their definitions are specific to Monitor alerts; this list doesn’t contain every parameter in every TML file. Similarly, the parameter definitions may vary from object to object, since the parameters may have different roles in different objects.

a - f	g - p	s - v
answer_id column comparator condition creator cron day_of_month day_of_week display_name end_time filters frequency_granularity frequency_spec fqn	guid hour id metric_id minute monitor_alert month name oper percentage_change_condition personalised_view_id personalised_view_info pinboard_id pinboard_viz_id	second simple_condition start_time subscribed_user tables threshold time_zone type user_email username value values viz_id

a - f

g - p

s - v

frequency_granularity

percentage_change_condition

personalised_view_id

personalised_view_info

answer_id: The GUID of an Answer. Used in Monitor alert TML files to specify the KPI used to create the alert. If you are importing or editing a Liveboard, use the pinboard_viz_id section instead, and do not include answer_id.

You can find this string of letters and numbers at the end of the URL for an Answer.

column: The id of the column(s) being filtered on. When a Liveboard contains linked filters, or filters that affect visualizations based on more than one Worksheet, the primary filter column appears first in the list of columns in the TML. The linked filter column appears after the primary filter column.

comparator: The operator used in the condition of a Monitor threshold-based alert. The options are COMPARATOR_GT (greater than), COMPARATOR_LT (less than), COMPARATOR_GEQ (greater than or equal to), COMPARATOR_LEQ (less than or equal to), COMPARATOR_EQ (equal to), COMPARATOR_NEQ (not equal to), PERCENTAGE_CHANGE_COMPARATOR_CHANGES_BY (changes by %), PERCENTAGE_CHANGE_COMPARATOR_INCREASES_BY (increases by %), PERCENTAGE_CHANGE_COMPARATOR_DECREASES_BY (decreases by %). The PERCENTAGE_CHANGE operators are only valid if your KPI includes a time-series keyword, such as weekly.

condition: Container for the Monitor threshold-based alert condition. Contains either a simple condition or a percentage change condition. To change a threshold-based alert to a scheduled alert, remove the condition section.

creator

Container for information about the creator of a Monitor alert. The creator information is only visible for administrators.

Only administrators can change the owner/creator of an alert, and only at the time of alert creation. You can’t change the owner of an alert after the alert is created.

cron: Contains frequency information for delivery of Monitor alerts.

day_of_month: The numbered days of the month, 1-31, when a Monitor alert should be sent. For example, "3,18,25".

day_of_week: The numbered days of the week, 0-6, when a Monitor alert should be sent. For example, "0,3,5". 0 refers to Sunday, and 6 refers to Saturday.

display_name: The name or value that displays in the Parameter dialog for an accepted value, if a display name was set when creating a Parameter. For example, if the Parameter accepts true and false, the display names might be yes and no.

end_time: The epoch time at which the alert should end. This is almost always 0, which means the alert continues to be triggered indefinitely. Do not edit this parameter.

filters: Contains specifications for filters.

frequency_granularity: Frequency with which ThoughtSpot sends a Monitor alert, either HOURLY, DAILY, WEEKLY, or MONTHLY.

frequency_spec: Contains information about when ThoughtSpot sends a scheduled Monitor alert.

fqn: The source table’s GUID. You can find this string of letters and numbers at the end of the URL for that table or connection.

For example, in https://<company>.thoughtspot.com/#/data/tables/34226aaa-4bcf-4d6b-9045-24cb1e9437cb, the GUID is 34226aaa-4bcf-4d6b-9045-24cb1e9437cb.

Use this optional parameter to reduce ambiguity and identify a specific table, if you have multiple tables with the same name. When exporting a TML file, you have the option to Export FQNs of referenced objects, which ensures that the TML files you export contain FQNs for the underlying tables and connections. If you do not add the fqn parameter, and the connection or table you reference does not have a unique name, the file import fails.

guid: The GUID for the Monitor alert.

You can find this string of letters and numbers at the end of the URL for an object.

hour: Specifies the hour that a Monitor alert is scheduled to be sent. For example, if you specify 9 for the hour parameter and 17 for the minute parameter, ThoughtSpot sends the Monitor alert at 9:17 AM.

id: Specifies the id of an object, such as tables.

metric_id: Container for the KPI used in the Monitor alert.

minute: Specifies the minute that a Monitor alert is scheduled to be sent. For example, if you specify 9 for the hour parameter and 17 for the minute parameter, ThoughtSpot sends the Monitor alert at 9:17 AM.

monitor_alert: Top-level container for all object definitions within the Monitor alert.

month: The numbered months of the year (1-12, starting with January, even if you use a custom/fiscal calendar) in which the Monitor alert should be sent. For example, to send an alert only in March and September, specify '3,9'.

name: The name of an object. Applies to monitor_alert.

oper: The operator of the filter. Accepted operators are "in", "not in", "between", =<, !=, <=, >=, >, or <.

percentage_change_condition: Container for the Monitor threshold-based alert condition, if the alert condition involves a percentage change. If the alert condition involves a simple condition (greater than, less than, equal, not equal to, greater than or equal to, less than or equal to), ThoughtSpot uses simple_condition instead of percentage_change_condition.

personalised_view_id: ID of the personalised View the monitor alert is based on. If no personalised_view_id is included, this TML creates an alert with no ad-hoc filters applied. If a personalised_view_id is available and supplied as part of the metric_id, the filters and parameters applied to the personalised View are applied to create the contextual alert.

personalised_view_info: Container for the filters and parameters applied on the personalized View. If the TML contains only personalised_view_info and no personalised_view_id, the TML creates a new personalised View, and the contextual alert created uses the filters and parameters provided in the personalised_view_info.

pinboard_id: The GUID of a Liveboard. Used in Monitor alert TML files to specify the KPI used to create the alert. If you are importing or editing an Answer, use answer_id instead, and do not include any part of the pinboard_viz_id section.

You can find this string of letters and numbers at the end of the URL for a Liveboard.

pinboard_viz_id: Contains information about the KPI used to create a Monitor alert. If you are importing or editing an Answer, use answer_id instead, and do not include any part of the pinboard_viz_id section.

second: Specifies the second that a Monitor alert is scheduled to be sent. For example, if you specify "30" for the second parameter, 9 for the hour parameter, and 17 for the minute parameter, ThoughtSpot sends the Monitor alert at 9:17 and 30 seconds. You can only specify seconds in TML, not in the UI.

simple_condition: Container for the Monitor threshold-based alert condition. If the alert condition involves a percentage change, ThoughtSpot uses percentage_change_condition instead of simple_condition.

start_time: The epoch time at which the user created the alert. Do not edit this parameter.

subscribed_user: List of users subscribed to a Monitor alert.

tables: List of tables used by the underlying KPI. Each table is defined by name.

threshold: Container for the threshold value in a Monitor threshold-based alert.

time_zone: Specifies the timezone ThoughtSpot should use when sending an alert. For example, if you live in New York City (ET) and are creating an alert for someone in Los Angeles (PST), you may want to specify that the alert should be sent at 9 AM in the America/Los_Angeles timezone. Specify the timezone with the full name: America/Los_Angeles, not PST.

type: The type of date filter.

user_email

The email address of the creator of a Monitor alert, or the email addresses of subscribed users for a Monitor alert. The creator information is only visible for administrators. If you specify both a username and a user_email for the creator of a Monitor alert, the username specified takes precedence. If the user_email is the only parameter specified and multiple ThoughtSpot users have that email address, the TML validation returns an error, and you must specify a username.

Only administrators can change the owner/creator of an alert, and only at the time of alert creation. You can’t change the owner of an alert after the alert is created.

username

The username of the creator of a Monitor alert, or the usernames of subscribed users for a Monitor alert. The creator information is only visible for administrators. If you specify both a username and a user_email for the creator of a Monitor alert, the username specified takes precedence.

Only administrators can change the owner/creator of an alert, and only at the time of alert creation. You can’t change the owner of an alert after the alert is created.

value: The threshold value in a Monitor threshold-based alert, or an accepted value for a Parameter, if a list was configured when creating a Parameter.

values: The values being filtered (excluded or included) in a Liveboard.

viz_id: The GUID of a Liveboard visualization. Used in Monitor alert TML files to specify the KPI used to create the alert. If you are importing or editing an Answer, use answer_id instead, and do not include any part of the pinboard_viz_id section.

You can find this string of letters and numbers at the end of the URL for a Liveboard visualization. Under the visualization’s more menu, select Copy link. The link copies to your clipboard. The second string of letters and numbers in the URL is the visualization GUID.

Limitations of working with TML files

There are certain limitations to the changes you can apply by editing Monitor alerts through TML.

You can’t import manually compressed .zip files. You can only import .zip files that you exported from ThoughtSpot: a custom set of TML files, an object and its associated data sources, or multiple objects of the same type that you exported from the object list page.

Was this page helpful?Give us feedback!

TML for Monitor alerts

Syntax of the Monitor alert TML file

TML parameters for Monitor alerts

Limitations of working with TML files

Product

By Role

By Department

Solutions

About Us

Connect