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.

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>
  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>
- 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 comparator condition creator cron day_of_month day_of_week end_time frequency_granularity frequency_spec	guid hour metric_id minute monitor_alert month name percentage_change_condition pinboard_id pinboard_viz_id	second simple_condition start_time subscribed_user threshold time_zone user_email username value viz_id

a - f

g - p

s - v

frequency_granularity

percentage_change_condition

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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