diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0598d166e..762bbdbb2 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,21 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== November 2025 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* + +The following enumerations are available for code based custom actions: + +* `CustomActionTarget` + +To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. +* `CustomActionsPosition` + +To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. +|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* +The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. +|==== + == Version 1.42.0, October 2025 [width="100%" cols="1,4"] diff --git a/modules/ROOT/pages/callback-response-payload.adoc b/modules/ROOT/pages/callback-response-payload.adoc index 238c5ce85..f40f6e312 100644 --- a/modules/ROOT/pages/callback-response-payload.adoc +++ b/modules/ROOT/pages/callback-response-payload.adoc @@ -283,6 +283,8 @@ The following example shows the data payload for a callback custom action in the } ---- + +//// === Liveboard payload (Classic experience) The following example shows the Liveboard data payload for a callback custom action on a Liveboard visualization: @@ -736,8 +738,10 @@ The following example shows the data payload for a callback custom action in the } ---- +//// + -=== Liveboard (New experience) +=== Liveboard The following example shows the data payload for a callback custom action in the *More* menu of a Liveboard visualization: diff --git a/modules/ROOT/pages/code-based-custom-actions.adoc b/modules/ROOT/pages/code-based-custom-actions.adoc new file mode 100644 index 000000000..27c92b8d0 --- /dev/null +++ b/modules/ROOT/pages/code-based-custom-actions.adoc @@ -0,0 +1,445 @@ += Code based custom actions +:toc: true +:toclevels: 2 + +:page-title: Code based custom actions +:page-pageid: code-based-custom-action +:page-description: You can add custom buttons or menu items in your ThoughtSpot code to the ThoughtSpot UI to let your application users to analyze insights and trigger an action on the data. + +Code-based custom actions are custom menu items that you define within the application's code through the Visual Embed SDK. These actions are executed when the user clicks on them. +Unlike the custom actions through the UI, this allows users to define custom actions using a few lines of code, specifying exactly where (target object) and how (placement in the UI) they should appear. +This makes it easier to implement these actions across Orgs, and also supports advanced customization. + +These custom actions add a new menu item to one of the following UI elements in an Answer, Liveboard, visualization, or in the Spotter interface: + +* the primary menu bar (except for Spotter) +* the **More** options menu image:./images/icon-more-10px.png[the more options menu] +* the contextual menu that appears when a user right-clicks on an Answer or visualization (except for Liveboard) + +[NOTE] +If a custom action for the primary menu bar is defined both in the ThoughtSpot UI and in the application code, only the action created through the UI will be shown. + + +=== Implementation of custom actions through the Visual Embed SDK + +Custom Actions can be embedded through the Visual Embed SDK in the following two ways: + +**Via the init function** + +* Custom actions can be registered globally during SDK initialization. +* This allows the action to be reused across multiple embedded objects. + +**Via individual embed functions** + +* Custom actions can be defined at the time of embedding a specific component like a Liveboard (LiveboardEmbed). +* This provides more granular control over where and how these actions are shown. + + +=== Components of a code based custom action interface + +[width="100%" cols="4,5"] +[options='header'] +|=== +|parameter|description + +|`name`|_String._ Display name for the custom action. +|`id`|_String._ Unique identifier for the action. +|`position` a|Position where the action should be rendered. Valid values include: + + +* `CustomActionsPosition.MENU` +* `CustomActionsPosition.PRIMARY` +* `CustomActionsPosition.CONTEXTMENU` + +|`target` a|The target object type where the action applies. Valid values include: + + +* `CustomActionTarget.LIVEBOARD` +* `CustomActionTarget.VIZ` +* `CustomActionTarget.ANSWER` +* `CustomActionTarget.SPOTTER` + +|`metadataIds` a|_Optional_. Metadata-based filtering for actions. Valid values include: + + +* `answerIds`:__Array of Strings.__ Applicable Answer ids. Unique identifier (GUID) for the Answer. +* `liveboardIds`: __Array of Strings.__ Applicable Liveboard ids. Unique identifier (GUID) for the Liveboard. +* `vizIds`: __Array of Strings.__ Applicable Viz ids. Unique identifier (GUID) for the Visualization. +|`dataModelIds` a|__Array of Strings.__ Unique identifier (GUID) for the data Model `modelIds` or column names `modelColumnNames`. Column names are represented in the array as : [`modelIds::columnName`]. +|`orgIds`|__Array of Strings.__ Restrict visibility to specific Orgs. Unique identifier for the org(s). +|`groupIds`|__Array of Strings.__ Restrict visibility to specific groups. Unique identifier for the group(s). +|=== + +=== Code based custom action for Liveboards + +The custom action is applied to all Liveboards. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.LIVEBOARD, +}, ]; +---- + +The custom action is applied on a specific Liveboard, the `liveboardIds` is passed in the `metadataIds`. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.LIVEBOARD, + metadataIds: { + liveboardIds: ['lb1'], + }, +}, ]; +---- + +The custom action is applied on a specific Liveboard with restricted visibility for a group of users in a particular Org. The `liveboardIds` is passed in the `metadataIds` along with the `groupId` and the `orgId`. + +[source,javascript] +---- +const customActions = [{ + name: "CA1", + id: "ca1", + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.LIVEBOARD, + metadataIds: { + liveboardId: ['lb1'], + }, + groupId: ['grp1'], + orgId: ['org1'], +}, ]; +---- + +=== Code based custom action for Visualizations + +The custom action is applied to all Visualizations. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, +}, ]; +---- + +The custom action is applied on all visualizations on a specific Liveboard, the `liveboardIds` is passed in the `metadataIds`. This custom action will also be visible to all new users who have access to the Liveboard. + + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, + metadataIds: { + liveboardIds: ['lb1'] + }, +}, ]; +---- + +The custom action is applied on a specific visualization, the `vizIds` is passed in the `metadataIds`. In this example, the custom action +will be shown on viz1 everywhere its pinned. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, + metadataIds: { + vizIds: ['viz1'] + }, +}, ]; +---- + + +When both `liveboardIds` and `vizIds` parameters are provided, the system will perform a union of all visualizations associated with the specified `liveboardIds` and the visualizations explicitly referenced by the provided `vizIds` values. + +In this example, Liveboard lb1 contains visualizations viz11 and viz12. Another Liveboard, lb2, contains visualizations viz21 and viz22. + +* For Liveboard lb2, a custom action will be displayed on all visualizations, since the liveboardId is present. + +* The custom action will also be shown only on the visualization with the id viz11 for Liveboard lb1. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, + metadataIds: { + liveboardIds: ['lb2'], + vizIds: ['viz21', 'viz11'] + }, +}, ]; +---- + +When either `groupId`, `orgId`, or both are provided, custom actions will be displayed only for the visualization for the members of the specified groupId within the specified orgId. + +In this example, Liveboard lb1 contains visualizations viz11 and viz12. Another Liveboard, lb2, contains visualizations viz21 and viz22. For a user who is part of org1 and grp1, + +* The custom action will be displayed on all visualizations of Liveboard lb2, since the liveboardId is present. + +* The custom action will also be shown for visualization viz11. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, + metadataIds: { + liveboardIds: ['lb2'], + vizIds: ['viz21', 'viz11'] + }, + groupId: ['grp1'], + orgId: ['org1'] +}, ]; +---- + +When the answerId parameter is provided, the system displays custom actions only on the visualization(s) that use the specified underlying answerId. + +In this example, consider a Liveboard (lb1) with three visualizations: viz1 (based on ans1), viz2 (based on ans2), and viz3 (based on ans3). + +* The custom action will be displayed on all visualizations of Liveboard lb2, since the liveboardId is present. + +* The custom action will also be shown for viz1 and viz 3, as viz1 is explicitly included by vizId, and viz3 uses the specified answerId (ans3) as its underlying data source. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: 'CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, + metadataIds: { + liveboardIds: ['lb2'], + vizIds: ['viz1'], + answerIds: ['ans3'] + }, +}, ]; + +---- + +When `modelIds` is passed in the `dataModelIds`, then the custom action is show for all visualization which are using the columns of the specified model. + +In this example: + +* The custom action will be displayed on all visualizations of Liveboard lb2, since the liveboardId is present. + +* The custom action will also be shown for all visualizations built using the column(s) of model1. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: 'CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, + metadataIds: { + liveboardIds: ['lb2'], + }, + dataModelIds: { + modelIds: ['model1'] + } +}, ]; + +---- + +When `modelColumnNames` are provided, the custom action will be displayed only on visualizations that are created using the specified `modelColumnNames`. + +In this example: + +* The custom action will be displayed on all visualizations of Liveboard lb2, since the liveboardId is present. + +* The custom action will also be shown for all visualizations built using the col1 of model1. + + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: 'CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, + metadataIds: { + liveboardIds: ['lb2'], + }, + dataModelIds: { + modelColumnNames: ["model1::col1"] + }, +}, ]; +---- + + + +In this example: + +* The custom action will be displayed on all visualizations of Liveboard lb2, since the liveboardId is present. +* If there is a model1 which has col1, col2, and a model2 which has col2, the custom action will be shown for visualizations or answers built using col2 of model1. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: 'CustomActionPosition.PRIMARY, + target: CustomActionTarget.VIZ, + metadataIds: { + liveboardIds: ['lb2'], + }, + dataModelIds: { + modelIds: ["model1"::"col2"], + }, +}, ]; + +---- + +=== Code based custom action for Answers + +The custom action is applied to all Answers. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionsPosition.PRIMARY, + target: CustomActionTarget.ANSWER, +}, ]; +---- + + +The custom action is applied on a specific Answer, the `answerIds` is passed in the `metadataIds`. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionsPosition.PRIMARY, + target: CustomActionTarget.ANSWER, + metadataIds: { + answerIds: ['ans1'], + }, +}, ]; + +---- + +When a `modelIds` is specified, the custom action will be displayed for all answers which use the specified model. + +In this example: + +* The custom action will be displayed for ans1, since the answerId is present. + +* The custom action will also be shown for all answers using model1. + +[source,javascript] +---- +const customActions = [{ + name: "CA1", + id: 'ca1', + position: CustomActionsPosition.PRIMARY, + target: CustomActionTarget.ANSWER, + metadataIds: { + answerIds: ['ans1'], + }, + dataModelIds: { + modelIds: [model1], + }, +}, ]; +---- + +When a `modelColumnNames` is specified, the custom action will be displayed for all answers which use the specified model. + +In this example: + +* The custom action will be displayed for ans1, since the answerId is present. + +* The custom action will also be shown for all answers using col1 from model1. + +[source,javascript] +---- +const customActions = [{ + name: "CA1", + id: 'ca1', + position: CustomActionsPosition.PRIMARY, + target: CustomActionTarget.ANSWER, + metadataIds: { + answerIds: ['ans1'], + }, + dataModelIds: { + modelColumnNames: ["model1::col1"], + }, +}, ]; +---- + +When either `groupId`, `orgId`, or both are provided, custom actions will be displayed only for the members of the specified groupId within the specified orgId, on the answers with the given answerId. + +In this example, the custom action will be displayed on ans1 for users who are a part of org1, and also a member grp1. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionsPosition.PRIMARY, + target: CustomActionTarget.ANSWER, + metadataIds: { + answerIds: ['ans1'], + }, + groupId: ['grp1'], + orgId: ['org1'], +}, ]; + +---- + +=== Code based custom action for Spotter + +When a `modelIds` is specified, custom actions will be displayed on all answers and visualizations generated from that model, as well as in any Liveboard where these answers have been pinned. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.MENU, + target: CustomActionTarget.SPOTTER, + dataModelIds: { + modelIds: ['model1'] + }, +}, ]; +---- + + +When either `groupId`, `orgId`, or both are provided, custom actions will be displayed on all answers and visualizations generated from that model, as well as in any Liveboard where these answers have been pinned. This will be shown only for the members with the specific groupId within the specified orgId. + +In this example, for a user who is part of org1 and grp1, + +* The custom action will be displayed for answers and visualizations generated from model1. + +* The custom action will also be shown in any Liveboard where these answers have been pinned. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.MENU, + target: CustomActionTarget.SPOTTER, + dataModelIds: { + modelIds: ['model1'] + }, + groupId: ['grp1'], + orgId: ['org1'] +}, ]; +---- \ No newline at end of file diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 048de7dda..8f7e34007 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -97,13 +97,14 @@ **** link:{{navprefix}}/actions[Action IDs in the SDK] *** link:{{navprefix}}/events-app-integration[Events and app interactions] *** link:{{navprefix}}/custom-action-intro[Custom actions] -**** link:{{navprefix}}/customize-actions[Create and manage custom actions] +**** link:{{navprefix}}/customize-actions[Custom actions through the UI] ***** link:{{navprefix}}/custom-action-url[URL actions] ***** link:{{navprefix}}/custom-action-callback[Callback actions] ***** link:{{navprefix}}/custom-action-payload[Callback response payload] -**** link:{{navprefix}}/edit-custom-action[Set the position of a custom action] -**** link:{{navprefix}}/add-action-viz[Add a local action to a visualization] -**** link:{{navprefix}}/add-action-worksheet[Add a local action to a worksheet] +***** link:{{navprefix}}/edit-custom-action[Set the position of a custom action] +***** link:{{navprefix}}/add-action-viz[Add a local action to a visualization] +***** link:{{navprefix}}/add-action-worksheet[Add a local action to a worksheet] +**** link:{{navprefix}}/code-based-custom-action[Code based custom actions] *** link:{{navprefix}}/customize-links[Customize links] *** link:{{navprefix}}/set-locale[Customize locale] *** link:{{navprefix}}/custom-domain-config[Custom domain configuration] @@ -208,6 +209,8 @@ include::generated/typedoc/CustomSideNav.adoc[] ** link:{{navprefix}}/v1v2-comparison[REST v1 and v2.0 comparison] ** link:{{navprefix}}/graphql-guide[GraphQL API ^Beta^] ** link:{{navprefix}}/webhooks[Webhooks] +*** link:{{navprefix}}/webhooks-kpi[Webhook for KPI alerts] +*** link:{{navprefix}}/webhooks-lb-schedule[Webhook for Liveboard schedule events ^Beta^] * link:{{navprefix}}/development-and-deployment[Deployment and integration] ** link:{{navprefix}}/development-and-deployment[Development and deployment] diff --git a/modules/ROOT/pages/connections.adoc b/modules/ROOT/pages/connections.adoc index ad7efa1b3..bccbca98d 100644 --- a/modules/ROOT/pages/connections.adoc +++ b/modules/ROOT/pages/connections.adoc @@ -22,6 +22,8 @@ ThoughtSpot supports connecting to external data warehouses and using these as d * https://docs.thoughtspot.com/cloud/latest/connections-synapse[Azure Synapse] +* https://docs.thoughtspot.com/cloud/latest/connections-clickhouse[ClickHouse] [earlyAccess eaBackground]#Early Access# + * https://docs.thoughtspot.com/cloud/latest/connections-databricks[Databricks] * https://docs.thoughtspot.com/cloud/latest/connections-denodo[Denodo] @@ -149,6 +151,30 @@ __String__. Specify the database associated with the account. To set up a *Synapse connection with OAuth*, see https://docs.thoughtspot.com/cloud/latest/connections-synapse-oauth[Configure OAuth for a Synapse connection, window=_blank] ==== +.ClickHouse connection + +[%collapsible] +==== +* `host` ++ +__String__. The hostname of the ClickHouse server. + +* `port` ++ +_Integer_. Enter the ClickHouse server port number. + +* `user` ++ +_String_. Username of your ClickHouse database account. + +* `password` ++ +__String__. Password of your ClickHouse database account. + +* `Connection name` ++ +__String__. Name for the new ClickHouse connection. +==== .Databricks connection diff --git a/modules/ROOT/pages/custom-actions-callback.adoc b/modules/ROOT/pages/custom-actions-callback.adoc index 300c46dd3..3a7df7ccd 100644 --- a/modules/ROOT/pages/custom-actions-callback.adoc +++ b/modules/ROOT/pages/custom-actions-callback.adoc @@ -15,7 +15,6 @@ Callback custom actions allow you to get data payloads from an embedded ThoughtS * Callback custom actions are supported on embedded ThoughtSpot instances only and require a ThoughtSpot Embedded Edition license. * Users with developer or admin privileges can create a callback custom action in the Developer portal. * Developers can set a callback action as a global or local action. -* To access callback actions, users must have the **New Answer Experience** enabled on their application instance. * Users with edit permissions to a Model or visualization can add a local callback action to a visualization or Answer of their choice. * Developers must register the callback in the Visual Embed SDK and define data classes and functions to parse and process the JSON data payload retrieved from the callback event. -- diff --git a/modules/ROOT/pages/custom-actions-url.adoc b/modules/ROOT/pages/custom-actions-url.adoc index e298883e6..eb1b719fb 100644 --- a/modules/ROOT/pages/custom-actions-url.adoc +++ b/modules/ROOT/pages/custom-actions-url.adoc @@ -16,8 +16,7 @@ ThoughtSpot allows you to add a custom action to trigger a data payload to a spe * Any ThoughtSpot user with admin or developer privileges can create URL custom actions in the Developer portal. * URL actions are available on both embedded and standalone ThoughtSpot instances and do not require ThoughtSpot Embedded Edition license. * Developers can set a URL action as a global or local action. -* Developers can limit custom action access to a specific user group. -* To access a URL action, users must have the **New Answer Experience** enabled. +* Developers can limit custom action access to a specific user group. * For URL actions to work in the embedded mode, you must add the URL domain to the CORS and CSP connect-src allowlist. * Only ThoughtSpot users with edit permissions to a Model or visualization can add a URL action to a Model, visualization, or saved Answer. -- diff --git a/modules/ROOT/pages/custom-actions-viz.adoc b/modules/ROOT/pages/custom-actions-viz.adoc index 0dc50f6b4..552581493 100644 --- a/modules/ROOT/pages/custom-actions-viz.adoc +++ b/modules/ROOT/pages/custom-actions-viz.adoc @@ -21,7 +21,6 @@ If you have access to a custom action, ThoughtSpot lets you perform the followin Perform the following checks: -* The link:https://docs.thoughtspot.com/cloud/latest/answer-experience-new[new Answer experience, window=_blank] is enabled on your cluster. * The custom action is available on your instance and is set as *Local*. * You have edit permission to modify the visualization or saved Answer. diff --git a/modules/ROOT/pages/custom-actions-worksheet.adoc b/modules/ROOT/pages/custom-actions-worksheet.adoc index 3a3579d2b..fe009ca8a 100644 --- a/modules/ROOT/pages/custom-actions-worksheet.adoc +++ b/modules/ROOT/pages/custom-actions-worksheet.adoc @@ -16,7 +16,6 @@ When you assign a custom action to a Model, ThoughtSpot adds it to the Answers g * Make sure the custom actions are set as *Local*. * Make sure you have edit permissions to modify the Model. -* Make sure the link:https://docs.thoughtspot.com/cloud/latest/answer-experience-new[new Answer experience, window=_blank] is enabled on your cluster. == Assign a custom action to a Model diff --git a/modules/ROOT/pages/custom-actions.adoc b/modules/ROOT/pages/custom-actions.adoc index a7f011da7..7bf7db71e 100644 --- a/modules/ROOT/pages/custom-actions.adoc +++ b/modules/ROOT/pages/custom-actions.adoc @@ -6,23 +6,27 @@ ThoughtSpot provides a set of standard menu commands and buttons, controlled via xref:embed-actions.adoc[actions]. -Custom actions add a new menu item to one of the following UI elements in an Answer or Liveboard visualization: +Custom actions add a new menu item to one of the following UI elements: * the primary menu bar * the **More** options menu image:./images/icon-more-10px.png[the more options menu] * the contextual menu that appears when a user right-clicks on an Answer or visualization + -[NOTE] -==== -The link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_vizpointclick[VizPointClick HostEvent] behaves in the same way as a context menu custom action, but fires immediately on a click rather than from the right-click context menu. -==== +Custom actions in ThoughtSpot can be implemented in two different ways: +* Custom actions through the UI +* Custom actions done programmatically (code based) + + +//// Custom actions are implemented in two parts: * *Within ThoughtSpot*, define the new menu item and its placement * *In the embedding app*, build code to receive the event and data when the user clicks the menu action. +//// -== Define custom actions in ThoughtSpot + +== Custom actions in the ThoughtSpot UI You must xref:customize-actions-menu.adoc[create custom actions] in the **Develop** > **Customizations** > **Custom actions** page of the ThoughtSpot UI. After a custom action has been created, there are several options for assigning how and where the custom action will appear: @@ -31,8 +35,75 @@ After a custom action has been created, there are several options for assigning * xref:custom-actions-worksheet.adoc[Assign custom actions to a Model] * xref:custom-actions-edit.adoc[Set the menu position of a custom action] +== Code based custom actions +Code-based custom actions are custom menu items that you define within the application's code through the Visual Embed SDK. + +These custom actions add a new menu item to one of the following UI elements in an Answer, Liveboard, visualization, or in the Spotter interface: + +* the primary menu bar (except for Spotter) +* the **More** options menu image:./images/icon-more-10px.png[the more options menu] +* the contextual menu that appears when a user right-clicks on an Answer or visualization (not for Liveboard) + +For more information, see xref:code-based-custom-actions.adoc[Code based custom actions]. + == Ways for embedding apps to receive custom actions -* xref:custom-actions-callback.adoc[Callback actions] + -Pass data and metadata from ThoughtSpot to the embedding page as an event. -* xref:custom-actions-url.adoc[URL actions] + -POST data directly to a specific web page or API endpoint destination. +**xref:custom-actions-callback.adoc[Callback actions]** + + +* Pass data and metadata from ThoughtSpot to the embedding page as an event. + +* Can be done through the ThoughtSpot UI or in the code through ThoughtSpot's Visual Embed SDK. + +**xref:custom-actions-url.adoc[URL actions]** + + +* POST data directly to a specific web page or API endpoint destination. + +* Only available through the ThoughtSpot UI. + +== Features comparison + +[width="100%" cols="4,5,5"] +[options='header'] +|=== +|Feature|Custom actions through the UI|Code based custom actions + +|Type|Callback actions + +URL based actions|Callback actions +|Scope|Answers + +Visualizations +Models +| +Answers + +Liveboards + +Visualizations + +Models +|Sharing|User groups|User groups +Orgs +|Liveboard menu|-|Primary menu + +More menu +|Visualization menu|Primary menu + +More menu + +Contextual menu|Primary menu + +More menu + +Contextual menu +|Answer menu|Primary menu + +More menu + +Contextual menu|Primary menu + +More menu + +Contextual menu +|Spotter |-|More menu + +Contextual menu +|=== + diff --git a/modules/ROOT/pages/customize-actions-menu.adoc b/modules/ROOT/pages/customize-actions-menu.adoc index 29a2ee0c5..2ce475de4 100644 --- a/modules/ROOT/pages/customize-actions-menu.adoc +++ b/modules/ROOT/pages/customize-actions-menu.adoc @@ -8,6 +8,12 @@ The custom actions feature in ThoughtSpot allows users to push data to external applications. To allow ThoughtSpot users to quickly act on the data they analyze, custom actions must be pre-configured in their setup. ThoughtSpot users with developer or admin privileges can create various types of custom actions in the **Develop ** tab and make them available on a saved Answer or visualization page. +[NOTE] +==== +The link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_vizpointclick[VizPointClick HostEvent] behaves in the same way as a context menu custom action, but fires immediately on a click rather than from the right-click context menu. +==== + + [div boxDiv boxFullWidth] -- +++
Feature highlights
+++ diff --git a/modules/ROOT/pages/customize-email-apis.adoc b/modules/ROOT/pages/customize-email-apis.adoc index b4e4d1cda..88370f384 100644 --- a/modules/ROOT/pages/customize-email-apis.adoc +++ b/modules/ROOT/pages/customize-email-apis.adoc @@ -11,7 +11,6 @@ ThoughtSpot now provides REST APIs that enable developers and administrators to * Sharing of Liveboards, visualizations, or saved answers * SpotIQ analysis results * KPI chart alerts -* Liveboard schedules These APIs support customizations of the following parameters of the email template at the Org level: diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index 41d7a841d..5bcfcf105 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -247,7 +247,9 @@ Contact ThoughtSpot support to enable these settings for PNG downloads on your T [IMPORTANT] ==== -* If the above settings are enabled on your instance or you are using a ThoughtSpot release 10.9.0.cl or later, you will no longer be able to use the `include_cover_page`,`include_filter_page` within the `png_options`. +* If the above settings are enabled on your instance or you are using a ThoughtSpot release 10.9.0.cl or later, +** You will no longer be able to use the `include_cover_page`,`include_filter_page` within the `png_options`. +** PNG download will support exporting only one tab at a time. If the `tab_identifier` is not specified, the first tab will be downloaded. * Due to UI limitations in the REST API Playground, you'll notice that some parameters are automatically included in the PNG options JSON. This may cause your API request to fail. As a workaround, click *View JSON* next to the `png_options`, review the parameters, remove additional parameters, and then click *Try it out*. ==== diff --git a/modules/ROOT/pages/get-started-tse.adoc b/modules/ROOT/pages/get-started-tse.adoc index 87a7b20c0..6ae6aa288 100644 --- a/modules/ROOT/pages/get-started-tse.adoc +++ b/modules/ROOT/pages/get-started-tse.adoc @@ -17,7 +17,8 @@ To embed ThoughtSpot in your app using the Visual Embed SDK and REST APIs, you m |*Embed Add-on*| Add-on license available for ThoughtSpot Analytics application users. + Allows embedding ThoughtSpot components in your internal business application. For example, you can embed a ThoughtSpot Liveboard in the app used by the employees of your organization. + This license provides full access to the Visual Embed SDK, REST APIs, security settings, and customization features. -|*ThoughtSpot Embedded*| Allows embedding ThoughtSpot components in your customer-facing products or publicly available applications. For example, you can embed a ThoughtSpot Liveboard in the application that is intended for customers and clients outside your organization. + +|*ThoughtSpot Embedded*| Allows embedding ThoughtSpot components in your customer-facing products or publicly available applications. For example, you can embed a ThoughtSpot Liveboard in the application that is intended for customers and clients outside your organization. ++ For more information about ThoughtSpot Embedded license editions, see link:https://www.thoughtspot.com/pricing[ThoughtSpot Website, window=_blank]. |===== diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index d42224b5c..d88e77098 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -8,7 +8,7 @@ ThoughtSpot’s Agentic Model Context Protocol (MCP) Server allows you to integrate ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. -The ThoughtSpot MCP Server is an add-on feature available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. + + The ThoughtSpot MCP Server is an add-on feature available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. + To purchase the MCP Server subscription and enable the MCP Server in your environment, you must have an active subscription to one of the following ThoughtSpot license plans: * Enterprise Edition of ThoughtSpot Analytics @@ -40,6 +40,7 @@ The `getRelevantQuestions` tool to fetch relevant data questions for a given dat * `getAnswer` to execute the queries and fetch data + The `getAnswer` tool generates answers and insights for a given data context. * `createLiveboard` to create a Liveboard in ThoughtSpot + + The `createLiveboard` tool calls the Liveboard creation workflow and creates a Liveboard with the answers generated from the user's query. //// @@ -48,6 +49,7 @@ Based on the type of data that users want to fetch, `getDataSourceSuggestions` g //// MCP client/ LLM agent:: + The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface and orchestrates interaction with the ThoughtSpot MCP Server. This is the model or system that processes the user’s natural language input, determines which tool to call, and integrates the tool results into its final output. @@ -59,6 +61,7 @@ Integration requires configuration, typically via a config file, to specify serv Authentication and security settings:: * Access to ThoughtSpot instance: + + For MCP Server connection, users require access to a ThoughtSpot instance. For tool invocation, the MCP server must accept authenticated requests, and the LLM tool specification must carry those credentials or headers. + ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in users. + * SAML redirect settings: + @@ -77,6 +80,7 @@ The MCP Server integration with an agentic framework or LLM clients enables the . User sends a query to get data from a specific ThoughtSpot data model context. . The LLM / AI agent receives the request and sends it to the MCP server endpoint with the user's query. . The MCP server responds with the available tools. + . The LLM / AI Agent determines the appropriate MCP tool to call. Based on the user's query or prompt, the MCP tools are invoked. For example, to get information for a specific data context from ThoughtSpot, break down the user's query into relevant questions or programmatically create an artifact in ThoughtSpot. . The MCP server processes the request and returns the result. . The agent receives the response, constructs the output, and presents it to the user. diff --git a/modules/ROOT/pages/publishing-overview.adoc b/modules/ROOT/pages/publishing-overview.adoc index dabe14ab6..973652808 100644 --- a/modules/ROOT/pages/publishing-overview.adoc +++ b/modules/ROOT/pages/publishing-overview.adoc @@ -14,7 +14,7 @@ Starting with the 10.10.0.cl release, ThoughtSpot provides a set of REST APIs fo [IMPORTANT] ==== -The publishing feature—including the REST APIs for variable creation and update, metadata parameterization, and publishing content across Orgs—is in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +The publishing feature, including the REST APIs for variable creation and update, metadata parameterization, and publishing content across Orgs, is in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== == When to use publishing feature @@ -69,6 +69,9 @@ This variable supports modifying connection properties per principal (user or us The `CONNECTION_PROPERTY_PER_PRINCIPLE` variable does not allow parameterizing core connection properties such as `accountName`, `host`, or `port`. These properties must be derived from the connection configuration and cannot be set per user or user group. + || + +`FORMULA_VARIABLE` a| `FORMULA_VARIABLE` refers can be used to create and manage formula variables. +| |===== The following figure illustrates variable substitution in Connections and Tables: diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 60cc36b23..a273ef782 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,7 +8,84 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. -== Version 10.14.0.cl, October 2025 +== Version 10.14.0.cl, November 2025 + +=== New API endpoints + +System:: +This release introduces the following endpoints for configuring communication channel preference. + +* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + +Sets a communication channel preference for all Orgs at the cluster level or at the indiviudal Org level. +* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + +Gets details of the communication channel preferences configured on ThoughtSpot. ++ +For more information, see xref:webhooks-lb-schedule.adoc#_configure_a_webhook_communication_channel_for_the_liveboard_schedule_event[Webhooks for Liveboard schedule events] + +Webhook:: +The following APIs are introduced for webhook CRUD operations: +* `POST /api/rest/2.0/webhooks/create` +Creates a webhook. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` +Updates the properties of a webhook +* `POST /api/rest/2.0/webhooks/search` +Gets a list of webhooks configured in ThoughtSpot or a specific Org in ThoughtSpot +* `POST /api/rest/2.0/webhooks/delete` +Deletes the webhook. ++ +For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. + +Column security rules:: + +* `POST /api/rest/2.0/security/column/rules/update` + +Updates column security rules for a given Table. + +* `POST /api/rest/2.0/security/column/rules/fetch` + +Gets details of column security rules for the tables specified in the API request. + +//// + +Spotter:: +POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse +//// +=== Variable API enhancements + +The following enhancements are introduced in variable API endpoints: + +Variable creation:: + +* You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in your API request to the `/api/rest/2.0/template/variables/create` endpoint. +* The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. + +Variables update:: +[tag redBackground]#BREAKING CHANGE# +* The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/{identifier}/update`. To update a variable, use the `POST /api/rest/2.0/template/variables/update` endpoint. +* The resource path for updating multiple variable values has changed from `/api/rest/2.0/template/variables/{identifier}/update` to `/api/rest/2.0/template/variables/update-values`. To assign values to one or several variables, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. + +Variables search:: +* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. +* Filtering API response by `EDITABLE_METADATA_AND_VALUES` output format is no longer supported. + +For more information, see xref:variables.adoc[Define variables]. + +=== User API enhancements +The following APIs now support `variable_values` parameter. The `variable_values` property can be used for user-specific customization. + +* `POST /api/rest/2.0/users/create` +* `POST /api/rest/2.0/users/search` +* `POST /api/rest/2.0/users/activate` + +=== DBT API enhancements +The `/api/rest/2.0/dbt/generate-tml` endpoint supports `model_tables` attribute to allow listing Models and its Tables. + +//// + +=== Authentication API +Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. + +//// + +== Version 10.13.0.cl, October 2025 === New API endpoints @@ -67,16 +144,6 @@ The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and rep The following API endpoints are now available: -//// -Column security rules:: - -* `POST /api/rest/2.0/security/column/rules/update` + -Updates column security rules for a given Table. - -* `POST /api/rest/2.0/security/column/rules/fetch` + -Gets details of column security rules for the tables specified in the API request. -//// - Custom calendar:: * `POST /api/rest/2.0/calendars/create` + Creates a custom calendar. diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 81cec2c87..c77028b36 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -24,6 +24,7 @@ Pass filter properties as query parameters in the URL. ==== * The runtime filters operation returns an error if the URL exceeds 2000 characters. * Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. +* When a Model has a column alias defined, ensure that the column name in the runtime filters reference the underlying base column name and not the column alias. ==== === Runtime filter properties diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 08b47f4eb..874f4e8b1 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -99,17 +99,24 @@ Note the following behavior in Spotter embedding: * If a user adds a Parameter to an answer through the edit flow, Spotter may drop this Parameter and any formulas using it in follow-up interactions. This means Parameters added in this way are not guaranteed to persist in subsequent conversational steps. === Adjust Parameter values using SDK events -After loading the embedded object, Parameters can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateparameters[HostEvent.UpdateParameters] event: +After loading the embedded object, Parameters can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateparameters[HostEvent.UpdateParameters] event as shown in these examples: [source,JavaScript] ---- liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: "Date List Param", value: 1656914873 - }, - { + isVisibleToUser: true + } +]) +---- + +[source,JavaScript] +---- +liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: "Integer Range Param", - value: 10 + value: 10, + isVisibleToUser: false } ]) ---- @@ -120,27 +127,96 @@ In Spotter embed, updating Parameters via host and embed events may not work. ==== === Show or hide Parameter chips in embedded sessions -Parameter values can be set or overridden using multiple methods. In some use cases, you may want to hide the Parameter chips from ThoughtSpot's UI, while in other cases you may want to show the chips. + +Parameter values can be set or overridden using the following methods: + +* Using the `runtimeParameters` property in ThoughtSpot's Visual Embed SDK. +* By triggering the `HostEvent.UpdateParameters` event in the SDK. To do this, load the page with parameters applied to the Liveboard or Answer, then override the parameter value using `HostEvent.UpdateParameters`. +* By applying a Parameter override directly in the URL (if you are not using the Visual Embed SDK). + +When a parameter is set or its value is overridden, the parameter chip is hidden from the embedded page view by default. + +In some cases, you may want the Parameter chips to show in the ThoughtSpot UI after they are set or modified. To support such use cases, the Visual Embed SDK allows you to set the `isVisibleToUser` attribute in the `HostEvent.UpdateParameters` event payload. + +The following table describes parameter chip behavior in common configuration scenarios: + +==== Parameter chip behavior +[width="100%" cols="5,7,8,8"] +[options='header'] +|===== +| How Parameter is set/updated +| Parameter chip behaviour (default) +| Update via `HostEvent.UpdateParameters`? +| Can make the chip visible via `isVisibleToUser`? + +| Via `runtimeParameters` in the Visual Embed SDK +| Hidden +| Possible +| No. + + +| Via URL parameter override +| Hidden +| Possible +| No. + +| Via `HostEvent.UpdateParameters` +| Hidden +| Possible +| Yes. The chip visibility can be overridden by setting `isVisibleToUser` to `true`. + +| Set initially via `runtimeParameters` in the SDK, and then updated via `HostEvent.UpdateParameters` +| Hidden +| Possible +| No. The chip visibility cannot be overridden by setting `isVisibleToUser` to `true`. +|===== + +[NOTE] +==== +If a Parameter chip is hidden, you cannot make it visible by changing the `isVisibleToUser` setting. +==== ==== Hide Parameter chips -To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading ThoughtSpot's page by using one of the following methods: +To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading the ThoughtSpot page using one of the following methods: -* Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK (Recommended) -* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK) +* Via `runtimeParameters` in Visual Embed SDK. +* By applying a Parameter override directly in the URL (if you are not using the Visual Embed SDK). -To update the parameter's value once the page is loaded, use `HostEvent.UpdateParameters`. The Parameter chip will remain hidden, however its value in ThoughtSpot's visualizations will be updated accordingly. +Additionally, setting the `isVisibleToUser` attribute to `false` in the `HostEvent.UpdateParameters` code in the SDK will hide the chip for the modified parameter. + +[source,JavaScript] +---- +liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ + name: "Integer Range Param", + value: 10, + isVisibleToUser: false +}]) +---- ==== Show Parameter chip in ThoughtSpot UI -To show the parameter chip from ThoughtSpot's user interface, update the Parameter's value with `HostEvent.UpdateParameters` after the page has loaded. The Parameter chip will then be shown and updated with each new value passed via the event. +To show the parameter chip in the ThoughtSpot UI, set the `isVisibleToUser` attribute to `true` in the `HostEvent.UpdateParameters` code and trigger the event after the page has loaded. The Parameter chip will then be displayed and updated with each new value passed via the event. +[source,JavaScript] +---- +liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ + name: "Integer Range Param", + value: 10, + isVisibleToUser: true +}]) +---- +//// [width="100%" cols="5,5,8"] [options='header'] |===== -|Parameter chip|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` + +|Parameter chip behavior|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` |Hidden|Yes| Possible |Shown| No| Possible |===== +//// + + == Apply Parameter overrides via REST API You can apply Parameter overrides to a Liveboard or Answer using REST v1 and v2 API endpoints. diff --git a/modules/ROOT/pages/theme-builder.adoc b/modules/ROOT/pages/theme-builder.adoc index 82231f07a..349f05820 100644 --- a/modules/ROOT/pages/theme-builder.adoc +++ b/modules/ROOT/pages/theme-builder.adoc @@ -1,4 +1,4 @@ -= Theme builder [beta betaBackground]^Beta^ += Theme builder :toc: true :toclevels: 2 diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc index cefffeb5d..27e3694af 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -6,9 +6,27 @@ :page-pageid: variables :page-description: Use the variables REST API to create and update variables for publishing content across Orgs -Variables allow you to define dynamic placeholders for specific properties of metadata objects such as Connections and Tables. By using variables, you can dynamically assign different values to the object properties for each Org and yet use a single source with a consistent data structure across different Orgs. +Variables allow you to define dynamic placeholders for specific properties of metadata objects, such as Connections and Tables. By using variables, you can dynamically assign different values to the object properties for each Org and yet use a single source with a consistent data structure across different Orgs. Before publishing an object to other Orgs, define variables for each Org and assign these variables to the metadata object properties. -Before publishing an object to other Orgs, define variables for each Org and assign these variables to the metadata object properties. +[IMPORTANT] +==== +Note the following enhancements and breaking changes introduced in ThoughtSpot Cloud 10.14.l0.cl release: + +* Variable creation + +** You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in your API request to the `/api/rest/2.0/template/variables/create` endpoint. +** The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. + +* Variables update and value assignment + +** The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/{identifier}/update`. To update a variable, use the `POST /api/rest/2.0/template/variables/update` endpoint. +** The resource path for updating multiple variable values has changed from `/api/rest/2.0/template/variables/{identifier}/update` to `/api/rest/2.0/template/variables/update-values`. To assign values to one or several variables, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. + +* Variable search + + +** The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. +** Filtering API response by `EDITABLE_METADATA_AND_VALUES` output format is no longer supported. + +ThoughtSpot recommends updating your application setup and workflows to avoid operational issues in your environment. +==== == Before you begin @@ -19,7 +37,7 @@ Before publishing an object to other Orgs, define variables for each Org and ass To create a variable, send a `POST` request to the +++/api/rest/2.0/template/variables/create +++ API endpoint, with the following parameters in the request body. === Request parameters -In your `POST` request body, you can include the following parameters: +In your `POST` request body, include the following parameters: [width="100%" cols="1,4"] [options='header'] @@ -34,12 +52,26 @@ To map Tables properties to variables. To define variables for connection properties. This variable allows editing connection properties such as `accountName`, `warehouse`, `user`, `password`, `role` and so on. * `CONNECTION_PROPERTY_PER_PRINCIPAL` + To define variables for connection properties per user or user group. This variable allows modifying connection properties such as `warehouse`, `role`, `user`, `password`. The `CONNECTION_PROPERTY_PER_PRINCIPLE` variable does not support modifying core connection properties such as `accountName`, `host`, or `port`. These properties must be derived from the connection configuration and cannot be set per user or user group. - -[NOTE] -This feature is disabled by default. To enable this option, contact ThoughtSpot Support. - +* `FORMULA_VARIABLE` + +Formula variables. |`name`| __String__. Name of the variable. For example, `schema_var`. Note that the name must be unique across all Orgs within the instance. |`sensitive` __Optional__ |__Boolean__. Indicates if the variable contains sensitive values such as passwords. +|`data_type` a|__String__. Variable data type. Required parameter for formula variables. Supported data types are: + +* `VARCHAR` + +String. For example, "East", "Administrator", "Secure", "2025-10-23" +* `INT32` + +32-bit integer data type. For example, 100,-42 +* `INT64` + +32-bit integer data type. For example, 0, 2147483647 +* `DOUBLE` + +The Double data type refers to a floating point numeric type that is recommended for storing decimal values. For example, 3.14, -0.001, 100.0, 1.7E+308. In ThoughtSpot, DOUBLE is used for columns that require floating point arithmetic or need to store decimal numbers, such as latitude and longitude or financial amounts. +* `DATE` + +Date format. For example, 2025-10-20. +* `DATE_TIME` + +Date with time stamp. For example, 2025-10-20 14:30:00. +|===== +//// |`values` __Optional__ a|__Array of strings__. Define the variable attributes. Although it's optional, make sure that you set the value for an Org before publishing content to that Org. The `values` array includes the following attributes: @@ -56,6 +88,8 @@ Applicable if the variable type is set as `CONNECTION_PROPERTY_PER_PRINCIPAL`. S Applicable if the variable type is set as `CONNECTION_PROPERTY_PER_PRINCIPAL`. The priority assigned to this value. If there are two matching values, the one with a higher priority will be used. |===== +//// + === Example request [source,cURL] @@ -66,23 +100,10 @@ curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "type": "TABLE_MAPPING", - "name": "schema_var", - "sensitive": false, - "values": [ - { - "value": "primary", - "org_identifier": "primaryOrg" - }, - { - "value": "TargetOrg1", - "org_identifier": "MyOrg1" - }, - { - "value": "TargetOrg2", - "org_identifier": "MyOrg2" - } - ] + "type": "FORMULA_VARIABLE", + "name": "my_formula_variable", + "is_sensitive": false, + "data_type": "DATE" }' ---- @@ -93,35 +114,31 @@ If the API request is successful, the following response is returned: [source,JSON] ---- { - "id": "180a9cd3-8605-445b-8b70-aa0bcef5dfb0", - "name": "schema_var", - "variable_type": "TABLE_MAPPING", - "sensitive": false, - "values": [ - { - "value": "primaryOrg", - "org_identifier": "Primary", - "principal_type": null, - "principal_identifier": null, - "priority": null - } - ] + "id": "3242b54c-69bc-4ff0-97cf-f99a2216b616", + "name": "my_formula_variable", + "variable_type": "FORMULA_VARIABLE", + "sensitive": true, + "values": [] } ---- Note the variable ID. + == Update variable values -To update a variable, the following APIs are available: +To update a variable or properties of a variable, use the following REST APIs: -* `+++POST /api/rest/2.0/template/variables/update+++` +* +++POST /api/rest/2.0/template/variables/{identifier}/update+++ + -Allows adding, removing, and replacing values for multiple variables in a single API call. +Allows updating the properties of a variable. -* `+++POST /api/rest/2.0/template/variables/{identifier}/update+++` +//* `+++POST /api/rest/2.0/template/variables/{identifier}/update+++` + +* +++POST /api/rest/2.0/template/variables/update-values+++ + -Allows adding, removing, and replacing values of a specific variable. +Allows adding, removing, and replacing values of one or several variables configured in ThoughtSpot. + === Update properties of a variable @@ -134,7 +151,12 @@ In your `POST` request body, you can include the following parameters: [width="100%" cols="1,4"] [options='header'] |===== -|Parameter|Description +|Parameter|Type|Description +|`identifier` |Path |__String__. Name or ID of the variable to update. +|`name`|Form parameter|__String__. Name of the variable. +|===== + +//// |`identifier` __String__| ID or name of the variable. Include the variable ID as a path parameter in the request body. |`name` __String__ | New name for the variable. Specify a name if you want to rename the variable. |`Operation` __String__ a| Specify the update operation type. The following options are available: @@ -157,24 +179,17 @@ Principal attributes such as user and user group. These attributes are applicabl * `priority` __Optional__ + The priority assigned to this value. Applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. |===== - +//// === Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/3242b54c-69bc-4ff0-97cf-f99a2216b616/update' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "operation": "REPLACE", - "name": "TableVar", - "values": [ - { - "value": "MyOrg`", - "org_identifier": "MyOrg1" - } - ] + "name": "formula_variable_test" }' ---- @@ -182,40 +197,48 @@ If the update operation is successful, the API returns a 204 response to indicat === Update properties of multiple variables -To update properties of multiple variables in a single call, send a `POST` request to the `/api/rest/2.0/template/variables/update` API endpoint with the following parameters in the request body. +To update properties of multiple variables in a single API call, send a `POST` request to the `POST /api/rest/2.0/template/variables/update-values` API endpoint. + +The API endpoint allows: +* Adding new values to variables +* Replacing existing values +* Resetting values === Request parameters In your `POST` request body, you can include the following parameters: -[width="100%" cols="1,4"] +[width="100%" cols="1,2,5"] [options='header'] |===== -|Parameter|Description -|`variable_updates` a|Array of inputs for the variable update. Allows updating the following properties for each variable ID in the array: - -* `identifier` __String__. + -ID or name of the variable to update. -* `variable_values` __Optional__ + -__Array of strings__. Assign new values for the variable attributes. - -** `value` __String__ + -The new value for the variable. for example, `staging1`. -** `org_identifier` __String__ + -ID or name of the Org. For primary Org, specify `primaryOrg` or Org 0. -** `principal_type` and `principal_identifier` __Optional__ + -Principal attributes such as user and user group. These attributes are applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. -** `priority` __Optional__ + -The priority assigned to this value. Applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. -|`Operation` __String__ a| Specify the update operation type. The following values are available: +|Parameter|Properties|Description +.4+|`variable_assignment` 2+| Properties for setting values for a variable at a specific entity level such as Org, user, or user-group. This allows the same variable to have different values depending on which entity is being referenced. +|`variable_identifier` a| __Array of strings__. Specify the variables to which you want to assign values. +|`variable_values` a|__Array of strings__. Specify the values to assign. For example, `staging1`. +|`operation` a| Specify the update operation type. The following values are available: * `ADD` + Adds new values. Use this operation type if you want to add new attributes to the variable. -* `REMOVE` + -Removes the values assigned to the variable specified in the API request. * `REPLACE` + Replaces the existing attributes with new values. +* `REMOVE` + +Removes the values assigned to the variable. For example, you can remove the values assigned to a formula variable configured for an Org. +* `RESET + +Resets all values at the variable level. For example, if a variable is assigned to multiple entities such as Org, user, or user group, the reset operation clears the values assigned to the variable for all entities. + +.5+|`variable_value_scope` 2+| Set the scope for variable values. +| `org_identifier` a|__String__ + +ID or name of the Org. For primary Org, specify `primaryOrg` or Org 0. +|`principal_type` and `principal_identifier` + +__Optional__ a|__String__. Principal attributes such as user and user group. These attributes are applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. +|`model_identifier` a| ID or name of the Model. +| `priority` + +__Optional__ a| +The priority assigned to this value. Applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. + +Priority refers to the order of precedence when updating variable values for multiple entities in a single operation. If more than one entity matches the conditions during variable resolution, based on the value assigned to the priority, the system determines which entity’s value takes effect. +For example, if both a user and their group have a value for the same variable, the system uses the priority to decide which value to apply. +|| |===== === Request example @@ -223,26 +246,25 @@ Replaces the existing attributes with new values. [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/update' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/update-values' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "variable_updates": [ + "variable_assignment": [ { "variable_identifier": "e61ace04-6651-4725-9174-90ce33423ef9", "variable_values": [ - { - "value": "prod1", - "org_identifier": "ProdOrg1" - }, - { - "value": "devOrg1", - "org_identifier": "devOrg" - } - ] + "prod1" + ], + "operation": "REPLACE" } ], - "operation": "REPLACE" + "variable_value_scope": [ + { + "org_identifier": "prodOrg", + "model_identifier": "Sampel retail sales" + } + ] }' ---- @@ -253,18 +275,21 @@ To get a list of variables or the details of a specific variable, send a `POST` To search for a variable, specify the following parameters in your API request: -* variable type -* variable ID -* Name pattern + -Specify partial name of the variable. For wildcard search, use `%`. -* output format + +* variable details + +Details such as variable type, ID, and name pattern. For name pattern search, specify the partial name of the variable. For wildcard search, use `%`. +* variable value + +Variable parameters such as Org ID, Model ID, ID and type of Principal object. +* output format for response content + Specify one of the following values for output format: ** `METADATA_ONLY` (default) + Returns only the variable metadata ** `METADATA_AND_VALUES` + Returns variable metadata and values + +//// ** `EDITABLE_METADATA_AND_VALUES` + Returns metadata details, such as name, type, default value, and whether the variable is editable, and the current values of variables that can be edited. +//// [source,cURL] ---- @@ -276,7 +301,7 @@ curl -X POST \ --data-raw '{ "record_offset": 0, "record_size": 10, - "output_format": "EDITABLE_METADATA_AND_VALUES", + "output_format": "METADATA_AND_VALUES", "variable_details": [ { "type": "TABLE_MAPPING" @@ -290,34 +315,36 @@ If the request is successful, the API returns the variable data in the response: [source,JSON] ---- [ - { - "id": "180a9cd3-8605-445b-8b70-aa0bcef5dfb0", - "name": "schema_var", - "variable_type": null, - "sensitive": null, - "values": [ - { - "value": "primaryOrg", - "org_identifier": "Primary", - "principal_type": null, - "principal_identifier": null, - "priority": null - }, - { - "value": "MyOrg1", - "org_identifier": "MyOrg1", - "principal_type": null, - "principal_identifier": null, - "priority": null - }, - { - "value": "MyOrg2", - "org_identifier": "MyOrg2", - "principal_type": null, - "principal_identifier": null, - "priority": null - }, - ] + { + "id":"180a9cd3-8605-445b-8b70-aa0bcef5dfb0", + "name":"schema_var", + "variable_type":null, + "sensitive":null, + "values":[ + { + "value":"primaryOrg", + "org_identifier":"Primary", + "principal_type":null, + "principal_identifier":null, + "priority":null + }, + { + "value":"MyOrg1", + "org_identifier":"MyOrg1", + "principal_type":null, + "principal_identifier":null, + "priority":null + }, + { + "value":"MyOrg2", + "org_identifier":"MyOrg2", + "principal_type":null, + "principal_identifier":null, + "priority":null + } + ] + } +] ---- == Delete a variable @@ -337,3 +364,5 @@ curl -X POST \ If the API request is successful, ThoughtSpot returns a 204 response code. + + diff --git a/modules/ROOT/pages/webhooks-kpi-alerts.adoc b/modules/ROOT/pages/webhooks-kpi-alerts.adoc new file mode 100644 index 000000000..e7ca4aeb9 --- /dev/null +++ b/modules/ROOT/pages/webhooks-kpi-alerts.adoc @@ -0,0 +1,309 @@ += Webhooks for KPI monitor alerts +:toc: true + +:page-title: Webhooks for KPI Monitor alerts +:page-pageid: webhooks-kpi +:page-description: Register a Webook to send KPI monitor alerts to an external application + +ThoughtSpot users with administrator or developer privileges can register a webhook to send Monitor alerts from a Key Performance Indicator (KPI) chart to an external application. KPI Monitor alerts notify users when a KPI metric meets a threshold condition or periodically as per the schedule configured by the user. + +For example, you can create an alert to be notified when a Sales KPI exceeds a threshold of 200,000, or when +your weekly sales increase by 2%. By default, the email notifications are sent to the alert subscriber’s email address. With webhooks, you can trigger alerts to the REST endpoint of an external application via HTTP POST requests and customize your application workflow to present these alerts as SMS messages or Slack notifications. + +//// + +[NOTE] +==== +The webhooks feature is in Beta and is turned off by default. To enable this feature on your instance, contact ThoughtSpot Support. +==== +//// + +== Before you begin + +* Make sure your ThoughtSpot user account has the privileges required to access the *Develop* page in the ThoughtSpot UI. +* Your destination application has a callback URL to accept HTTP POST requests. +* If you plan to use OAuth authentication, make sure you have the OAuth credentials and authorization URL of your application +* If you plan to use an API key for authentication, ensure that you have a valid API key. + +== Configure webhooks +To configure a webhook and send alert data to the destination URL, complete the following steps: + +* xref:webhooks.adoc#_register_a_webhook[Register a webhook in ThoughtSpot] +* xref:webhooks.adoc#_assign_webhook_to_a_kpi_monitor_alert[Assign the registered webhook to KPI Monitor alerts] + +=== Register a webhook + +To register a webhook in ThoughtSpot, complete the following steps: + +. Go to **Develop** > **Customizations** > **Webhooks**. ++ +If you are using the new experience, the *Developer* will be in the Application switcher image:./images/app_switcher.png[the app switcher menu]. + +. Click **Create Webhook**. +. In the ** Create Webhook** modal, specify the Webhook name and the URL of the destination application. ++ +For testing purposes, you can use a URL from the link:https://webhook.site/[Webhook site, window=_blank]. +. Specify the authentication type. +* No authentication + +Default authentication option. Not recommended for production environments. + +* API Key + +Allows using an API key to authenticate API requests to the destination URL. Specify the API key to use in the `X-API-Key` request header. + +* OAuthentication 2.0 + +Allows using OAuth credentials to authorize API requests. Specify client ID, client secret key, and authorization URL. +If the registered webhook has Oauth authentication enabled, `Authorization: Bearer ` is sent in the request header. +. If the destination URL requires query parameters to be passed in the request URL, specify the parameters as key-value pairs. +. Click **Save**. + +=== Assign webhook to a KPI Monitor alert + +To assign the registered webhook to an alert: + +* Go to a KPI chart and click the **Create alert** icon. + +If the alert is already configured, go to **Monitor** and click Edit alert to modify the alert properties. +* In the alert configuration modal, go to **Select notification channel** and select **Custom channel** and the webhook. +* Ensure that alert type and subscription details are defined. +* Click **Save**. + +Based on the type of alert, the notification payload will be sent in JSON format to the webhook URL via HTTP POST request. + +The following example shows the notification payload: + +[source,JSON] +---- +{ + "data": { + "currentUser": { + "displayName": "Guest 1", + "email": "guest1@thoughtspot.com" + }, + "schemaVersion": "v1", + "schemaType": "MONITOR", + "notificationType": "UPDATION", + "updationWebhookNotification": { + "modifyUrl": "", + "monitorRuleForWebhook": { + "scheduleString": "hourly every hour ", + "metricName": "Total Revenue Trend", + "alertType": "Scheduled", + "metricId": { + "pinboardVizId": { + "pinboardId": "22a8f618-0b4f-4401-92db-ba029ee13486", + "vizId": "ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb" + } + }, + "metricUrl": "http://{ThoughtSpot-Host}/?utm_source=kpi_monitor&utm_medium=webhook/#/pinboard/22a8f618-0b4f-4401-92db-ba029ee13486/ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb", + "ruleName": "Alert on Total Revenue Trend", + "conditionString": "", + "ruleId": "a4b0a1f4-279d-42ab-a710-4ba6964869fa" + }, + "unsubscribeUrl": "http://{ThoughtSpot-Host}/?utm_source=kpi_monitor&utm_medium=webhook/#/pinboard/22a8f618-0b4f-4401-92db-ba029ee13486/ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb?ts-type=unsubscribeFromRule&ts-ruleid=a4b0a1f4-279d-42ab-a710-4ba6964869fa" + } + } +} +---- + +== Webhook schema +The following Webhook schema is used when sending an HTTP POST request body to the registered Webhook URL: + +---- +WebhookNotification { + enum SchemaVersion, + enum EventSchemaType, + enum NotificationType, + User CurrentUser, + DeletionWebhookNotification deletionWebhookNotification, + FailureWebhookNotification failureWebhookNotification, + ScheduledMetricUpdateWebhookNotification scheduledMetricUpdateWebhookNotification, + SelfSubscriptionWebhookNotification selfSubscriptionWebhookNotification, + SubscriptionWebhookNotification subscriptionWebhookNotification, + ThresholdReachedMetricUpdateWebhookNotification thresholdReachedMetricUpdateWebhookNotification, + UpdationWebhookNotification updationWebhookNotification, +} +---- + +The fields are populated according to the notification type. For all types of notifications, the following four fields are populated: + +* SchemaVersion + +The version of the schema used + ++ +---- +enum SchemaVersion { + v1, +} +---- +* EventSchemaType + +Type of the schema used ++ +---- +enum EventSchemaType { + MONITOR, +} +---- +* NotificationType + +Type of the monitor notification sent ++ +---- +enum NotificationType { + SELF_SUBSCRIPTION, + DELETION, + UPDATION, + FAILURE, + SUBSCRIPTION, + SCHEDULE_METRIC_UPDATE, + THRESHOLD_METRIC_UPDATE, +} +---- +* CurrentUser + +User for which the notification is sent. ++ +---- +User { + String id, + String displayName, + String email, +} +---- + +Conditional fields include: + +* DeletionWebhookNotification deletionWebhookNotification + +Populated only when notificationType is DELETION. +* FailureWebhookNotification failureWebhookNotification + +Populated only when notificationType is FAILURE. +* ScheduledMetricUpdateWebhookNotification scheduledMetricUpdateWebhookNotification, + +Populated only when notificationType is SCHEDULE_METRIC_UPDATE. +* SelfSubscriptionWebhookNotification selfSubscriptionWebhookNotification, + +Populated only when notificationType is SELF_SUBSCRIPTION. +* SubscriptionWebhookNotification subscriptionWebhookNotification, + +Populated only when notificationType is SUBSCRIPTION. +* ThresholdReachedMetricUpdateWebhookNotification thresholdReachedMetricUpdateWebhookNotification, + +Populated only when notificationType is THRESHOLD_METRIC_UPDATE. +* UpdationWebhookNotification updationWebhookNotification + +Populated only when notificationType is UPDATION. + +The following examples show the schema for different alert notification types: + +=== Scheduled alert notification + +A scheduled alert is sent as per the configured periodicity. + +The following schema is used in the notification sent for scheduled alerts: +---- +ScheduledMetricUpdateWebhookNotification { + MonitorRuleForWebhook monitorRuleForWebhook, + String modifyUrl, + String unsubscribeUrl, + RuleExecutionDetails ruleExecutionDetails, +} +---- + +The following example shows the email notification for a scheduled alert: + +[.bordered] +image::./images/scheduledAlert.png[Scheduled alert] + +=== Threshold alert notification + +A threshold alert is sent when a metric in the KPI chart reaches the configured threshold. + +The following schema is used in the notification sent for threshold alerts: +---- +ThresholdReachedMetricUpdateWebhookNotification { + MonitorRuleForWebhook monitorRuleForWebhook, + String modifyUrl, + String unsubscribeUrl, + RuleExecutionDetails ruleExecutionDetails, +} +---- + +The following example shows the email notification for a threshold alert: + +[.bordered] +image::./images/thersholdAlert.png[threshold alert] + +=== SelfSubscription notification + +A self-subscription notification is sent for alerts self-subscribed by a user. + +The following schema is used in the notification sent for self-subscribed notifications: + +---- +SelfSubscriptionWebhookNotification { + MonitorRuleForWebhook monitorRuleForWebhook, + String modifyUrl, + String unsubscribeUrl, + RuleExecutionDetails ruleExecutionDetails, +} +---- + +The following example shows the email notification sent for a self-subscribed alert: + +[.bordered] +image::./images/userSubscribedAlert.png[User subscribed alert] + +=== Subscription notifications + +A subscription notification is sent when a user subscribes to a notification. + +The following schema is used in the subscription notification: + +---- +SubscriptionWebhookNotification { + MonitorRuleForWebhook monitorRuleForWebhook, + String modifyUrl, + String unsubscribeUrl, + RuleExecutionDetails ruleExecutionDetails, + User subscribedByUser, +} +---- + +The following example shows the email notification sent from ThoughSpot after a user subscribes to an alert: + +image::./images/subscriptionAlert.png[User subscribed alert] + +=== Delete Webhook notification + +A delete notification is sent to subscribers when an alert they subscribed to is deleted in ThoughtSpot. + +The following schema is used in the notification sent when an alert is deleted: + +---- +DeletionWebhookNotification { + String ruleName, + String metricName, + MetricId metricId, + User deletedByUser, +} +---- + +The following example shows the email notification sent to the subscribers when an alert is deleted: + +[.bordered] +image::./images/deleteAlert.png[delete webhook notification] + +=== Failure Webhook notification + +A failure notification is sent to subscribers when an alert execution fails. + +The following schema is used in the notification sent when a Webhook alert fails: + +---- +FailureWebhookNotification { + MonitorRuleForWebhook monitorRuleForWebhook, + String modifyUrl, + String unsubscribeUrl, + String reason, +} +---- + +The following example shows the email notification sent to the subscribers when an alert execution fails: + +[.bordered] +image::./images/failureAlert.png[Webhook failure notification] + +== Additional references + +* link:https://docs.thoughtspot.com/cloud/latest/monitor[Monitor alerts documentation, window=_blank] + + diff --git a/modules/ROOT/pages/webhooks-lb-schedule.adoc b/modules/ROOT/pages/webhooks-lb-schedule.adoc new file mode 100644 index 000000000..5d32220b7 --- /dev/null +++ b/modules/ROOT/pages/webhooks-lb-schedule.adoc @@ -0,0 +1,1019 @@ += Webhooks for Liveboard schedule events [beta betaBackground]^Beta^ +:toc: true +:toclevels: 3 + +:page-title: Webhooks for Liveboard Schedueld Jobs +:page-pageid: webhooks-lb-schedule +:page-description: Configure Webhooks and send alerts to specific communication channels + +To provide flexibility and programmatic control for users who want to customize notifications and automate workflows based on Liveboard scheduling events, ThoughtSpot provides the ability to configure a webhook communication channel. By configuring a webhook, users can send notifications automatically to a target application whenever a scheduled Liveboard job is triggered in ThoughtSpot. + +Webhook support for Liveboard schedule events is available only on ThoughtSpot Cloud instances running 10.14.0.cl or later. This feature is currently in beta and is not enabled by default. To enable this feature on your instance, contact ThoughtSpot Support. + +== Overview + +If you have scheduled a Liveboard job to receive a daily report via email, you can configure ThoughtSpot to send the report directly to a webhook endpoint and create your own custom emails or workflow. + +To automate sending scheduled Liveboard notifications to a webhook endpoint, the following configuration is required: + +* Ensure that "webhook" is selected as a communication channel for your Org or at the cluster level for all Orgs on your instance. Ensure that “webhook” is selected as the communication channel for your Org, or at the cluster level for all Orgs in your instance.+ +Use the following REST APIs to set and view communication channel preferences: +** `POST /api/rest/2.0/system/preferences/communication-channels/configure` +** `POST /api/rest/2.0/system/preferences/communication-channels/search` +* A webhook for the Liveboard schedule event to enable programmatic communication between the target application and ThoughtSpot. + +To create and manage webhook APIs, use the following APIs: +** `POST /api/rest/2.0/webhooks/create` +** `POST /api/rest/2.0/webhooks/delete` +** `POST /api/rest/2.0/webhooks/search` +** `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + +[NOTE] +==== +In the current release: + +* REST APIs support webhook channel configuration for `LIVEBOARD_SCHEDULE` events only. +* You can configure only one webhook for the Liveboard schedule event per Org. +==== + +== Get started +The webhooks setup for Liveboard Schedule events involves the following steps: + +* xref:webhooks-lb-schedule.adoc#_configure_webhook_communication_channel[Configuring a webhook communication channel at the cluster or Org level]. +* xref:webhooks-lb-schedule.adoc#_configure_a_webhook_for_liveboard_schedule_event[Creating a webhook to listen to the Liveboard schedule events]. +* xref:webhooks-lb-schedule.adoc#_verify_the_webhook_payload[Verifying the webhook payload]. + +=== Before you begin + +Check your application environment for the following prerequisites: + +* Ensure that you have access to a ThoughtSpot instance with the required permissions to set communication channel preferences, create and manage webhooks, and schedule Liveboard jobs. + +If your instance has Role-based Access Control (RBAC) enabled, you must have the `CAN_MANAGE_WEBHOOKS` privilege to create and manage webhooks. +* Ensure that the REST APIs for setting communication channel preference and configuring webhooks are enabled on your instance. If the APIs are not available on your instance, contact ThoughtSpot Support. +* To allow outbound traffic from the ThoughtSpot to the webhook endpoint, add the webhook destination URL to the xref:security-settings.adoc#csp-connect-src[CSP connect-src] allowlist in ThoughtSpot. +* Add the ThoughtSpot application URL as a trusted host in your Webhook destination endpoint/app. + +=== Configure a webhook communication channel + +To create a webhook communication channel for the Liveboard Schedule event, use the channel preference REST API. + +==== Create a webhook communication channel + +To create the webhook communication channel and set messaging preferences, send a `POST` request to the `/api/rest/2.0/system/preferences/communication-channels/configure` API endpoint. You can set preferences at the cluster level for all Orgs or at the Org level. When both are configured, the preferences set at the Org level take precedence. + +===== Request parameters + +[width="100%" cols="1,2,6"] +[options='header'] +|===== +|Parameter|Description | +.3+| `cluster_preferences` 2+|__Array of strings__. Sets default preferences for all Orgs in the instance. You must specify the following parameters: + +|`event_type` +a|__String__. Type of the event for which communication channels are configured. For Liveboard schedule event, set the parameter value as `LIVEBOARD_SCHEDULE`. + +|`channels` a| +__Array of strings__. Communication channel for the event type specified in the request. Valid values are: + + +* `EMAIL` +* `WEBHOOK` + +To create a webhook channel for the Liveboard schedule event, specify `WEBHOOK`. + +.5+| `org_preferences` 2+|__Array of strings__. By default, preferences configured at the cluster level will apply to all Orgs in the instance. To override the default preferences for your Org, set the Org-specific preferences: + +| `org_identifier` a| +__String__. Name or ID of the Org. +| `preferences` a| +__Array of strings__. Define the following parameters to set communication channel preferences for the Org. If the preferences are not set, the Org will inherit the default preferences applied at the cluster level. + +* `event_type` + +__String__. Type of the event for which communication channels are configured. For Liveboard schedule event, set the parameter value as `LIVEBOARD_SCHEDULE`. +* `channels` + +__Array of strings__. Communication channel for the event type specified in the request. Valid values are: + +** `EMAIL` +** `WEBHOOK` + ++ +To set up a webhook channel for the Liveboard schedule event, specify `WEBHOOK`. + +| `operation` a|__String__. Type of operation. The following options are available: + +** `REPLACE` - To replace default preferences. +** `RESET` - To restore default preferences. For reset operation, you'll also need to specify the event type. Note that this operation will remove any Org-specific overrides and restores the default preferences configured at the cluster level. + +|`reset_events` a|__Array of strings__. For RESET operations, specify the event type to reset. Note that the reset operation removes Org-specific configuration for the events specified in `reset_events`. +||| +|===== + +===== Example request + +The following example shows the request body for setting a communication channel preference at the cluster level. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/preferences/communication-channels/configure' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "cluster_preferences": [ + { + "event_type": "LIVEBOARD_SCHEDULE", + "channels": [ + "WEBHOOK" + ] + } + ] +}' +---- + +The following example shows the request body for setting a communication channel preference at the Org level. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/preferences/communication-channels/configure' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "org_preferences": [ + { + "org_identifier": "testOrg1", + "operation": "REPLACE", + "preferences": [ + { + "event_type": "LIVEBOARD_SCHEDULE", + "channels": [ + "WEBHOOK" + ] + } + ] + } + ] +}' +---- + +===== API response +If the request is successful, the API returns a 204 response. + +==== View the communication channel preferences + +To review and audit the communication channel preferences set on your instance, send a `POST` request to the `/api/rest/2.0/system/preferences/communication-channels/search` API endpoint. + +===== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter|Description + +|`cluster_preferences` + +__Optional__ a|__Array of strings__. To filter API response by event type, specify the event type for which the communication channel preference is set at the cluster level. +| `org_preferences` + +__Optional__ a|__Array of strings__. To filter API response by Org-specific overrides, specify the following parameters: + +* `org_identifier` + +__String__. Name or ID of the Org. +* `event_types` + +__Array of strings__. Event types to search for. To get channel preferences for Liveboard schedule events, specify `LIVEBOARD_SCHEDULE`. +|===== + +===== Example request + +The following request fetches channel preferences configured for the Liveboard schedule event at the cluster level: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/preferences/communication-channels/search' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "cluster_preferences": [ + "LIVEBOARD_SCHEDULE" + ] +}' +---- + +The following request fetches channel preferences configured for the Liveboard schedule event at the Org level: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/preferences/communication-channels/search' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "org_preferences": [ + { + "org_identifier": "testOrg1", + "event_types": [ + "LIVEBOARD_SCHEDULE" + ] + } + ] +}' +---- + +If the request is successful, the API returns a 204 response indicating successful operation. + +===== Example response + +The following example shows the communication preferences configured for the specified event type at the cluster level: + +[source,JSON] +---- +{ + "cluster_preferences": [], + "org_preferences": [ + { + "org": { + "id": "0", + "name": "Primary" + }, + "preferences": [] + }, + { + "org": { + "id": "1532970882", + "name": "testOrg" + }, + "preferences": [ + { + "event_type": "LIVEBOARD_SCHEDULE", + "channels": [ + "EMAIL", + "WEBHOOK" + ] + } + ] + }, + { + "org": { + "id": "2100019165", + "name": "testOrg1" + }, + "preferences": [ + { + "event_type": "LIVEBOARD_SCHEDULE", + "channels": [ + "WEBHOOK" + ] + } + ] + } + ] +} +---- + +The following example shows the preferences returned for a specific Org: + +[source,JSON] +---- +{ + "cluster_preferences": [], + "org_preferences": [ + { + "org": { + "id": "2100019165", + "name": "testOrg1" + }, + "preferences": [ + { + "event_type": "LIVEBOARD_SCHEDULE", + "channels": [ + "WEBHOOK" + ] + } + ] + } + ] +} +---- + +=== Configure a webhook + +To configure webhooks for the Liveboard schedule event, use the webhook REST API. + +==== Create a webhook + +To create a webhook for the Liveboard schedule event, send a `POST` request to the `/api/rest/2.0/webhooks/create` API endpoint. ThoughtSpot allows only one webhook per Org. + +===== Request parameters + +[width="100%" cols="1,6"] +[options='header'] +|===== +|Parameter|Description +| `name` a|__String__. Name of the webhook. +| `description` + +__Optional__ a|__String__. Description text for the webhook +| `url` a|__String__. The fully qualified URL of the listening endpoint where the webhook payload will be sent. The webhook endpoint to which you want to send notifications. +|`url_params` a| A JSON map of key-value pairs of parameters to add as a GET query params in the webhook URL. +| `events` a|__Array of strings__. List of events to subscribe to. Specify the event as `LIVEBOARD_SCHEDULE`. +|`authentication` a| + +Defines authentication method and credentials that ThoughtSpot will use when sending HTTP requests to the webhook endpoint. + +Specify the authentication type. + +* `API_KEY` + +API key to authorize the payload requests. Specify the API key to use in the `X-API-Key` request header. +* `BASIC_AUTH` + +Authentication methods with username and password. +* `BEARER_TOKEN` + +Authentication token to authenticate and authorize requests. +* `OAUTH2` + +OAuth credentials to authorize API requests. Specify client ID, client secret key, and authorization URL. +If the registered webhook has Oauth authentication enabled, `Authorization: Bearer ` is sent in the request header. +|`signature_verification` + +__Optional__ a| Signature verification parameters for the webhook endpoint to verify the authenticity of incoming requests. This typically involves ThoughtSpot signing the webhook payload with a secret, and your webhook endpoint validating this signature using the shared secret. + +If using signature verification, specify the following parameters. + +* `type` + +Signature verification type. Supported type is `HMAC_SHA256`, which uses Hash-based Message Authentication Code (HMAC) algorithm with the SHA-256 hash function to generate a cryptographic signature for webhook payloads. When configured, ThoughtSpot will sign the webhook payload using a shared secret and the HMAC_SHA256 algorithm. Your receiving endpoint should use the same secret and algorithm to compute the HMAC of the received payload and compare it to the signature sent by ThoughtSpot. + +* `header` + +HTTP header where the signature is sent. +* `algorithm` + +Hash algorithm used for signature verification. +* `secret` + +Shared secret used for HMAC signature generation. +|===== + +===== Example request +The following example shows the request body for creating a webhook: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "name": "webhook-lb-event", + "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d", + "events": [ + "LIVEBOARD_SCHEDULE" + ], + "authentication": { + "BEARER_TOKEN": "Bearer {AUTH_TOKEN}" + } + "description": "Webhook for Liveboard schedule" +}' +---- + +===== Example response + +If the webhook creation is successful, the API returns the following response: + +[source,JSON] +---- +{ + "id": "873dd4e2-6493-490d-a649-ba9ea66b11f5", + "name": "webhook-lb-event", + "description": "Webhook for Liveboard schedule", + "org": { + "id": "2100019165", + "name": "testOrg1" + }, + "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d", + "url_params": null, + "events": [ + "LIVEBOARD_SCHEDULE" + ], + "authentication": BEARER_TOKEN, + "signature_verification": null, + "creation_time_in_millis": 1761050197164, + "modification_time_in_millis": 1761050197164, + "created_by": { + "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "name": "UserA@thoughtspot.com" + }, + "last_modified_by": null +} +---- + +==== View webhook properties + +To view the properties of a webhook or get a list of webhooks configured on your ThoughtSpot instance, send a `POST` request to the `/api/rest/2.0/webhooks/search` API endpoint. + +To get specific information, define the following parameters. If the API request is sent without any parameters in the request body, ThoughtSpot returns the webhooks configured for the Org contexts in ThoughtSpot. + +===== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter|Description +| `org_identifier` + +__Optional__ |__String__. ID or name of the Org. +| `webhook_identifier` + +__Optional__ | __String__. ID or name of the webhook. +|`event_type` + +__Optional__| __String__. Type of webhook event to filter by. For Liveboard schedule events, specify `LIVEBOARD_SCHEDULE`. +|Pagination settings a| If fetching multiple records, specify the following parameters to paginate API response: + + +* `record_offset` + +__Integer__. Specifies the starting point (index) from which records should be returned. Default is 0. +* `record_size` + +__Integer__. Specifies the number of records to return in the response. Default is 50. +| `sort_options` + +__Optional__| Enables sorting of the API response by a specific field in ascending or descending order. Specify the `field_name` and define the desired sort order. +| +|===== + +===== Example request + +The following example shows the request body to fetch webhook properties: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/search' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "record_offset": 0, + "record_size": 50, + "org_identifier": "testOrg1", + "event_type": "LIVEBOARD_SCHEDULE" +}' +---- + +===== Example response + +If the API request is successful, ThoughtSpot returns the webhook configuration details: + +[source,JSON] +---- +{ + "webhooks": [ + { + "id": "873dd4e2-6493-490d-a649-ba9ea66b11f5", + "name": "webhook-lb-event", + "description": "Webhook for Liveboard schedule", + "org": { + "id": "2100019165", + "name": "testOrg1" + }, + "url": "https://webhook.site/view/6643eba5-9d3e-42a1-85e0-bb686ba1524d/29c02fc2-c1c6-4b20-8d62-e8d51cf8dfb3", + "url_params": null, + "events": [ + "LIVEBOARD_SCHEDULE" + ], + "authentication": null, + "signature_verification": null, + "creation_time_in_millis": 1761050197164, + "modification_time_in_millis": 1761051944507, + "created_by": { + "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "name": "UserA@thoughtspot.com" + }, + "last_modified_by": { + "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "name": "UserA@thoughtspot.com" + } + } + ], + "pagination": { + "record_offset": 0, + "record_size": 50, + "total_count": 1, + "has_more": false + } +} +---- + +==== Update the properties of a webhook + +To update the name, description text, endpoint URL, or the authentication settings of a webhook object, send a `POST` request to the `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint. + +===== Request parameters + +Specify the `webhook_identifier` and pass it as a path parameter in the request URL. + +The API operation allows you to update the following webhook properties: + +* `name` + +Name of the webhook. +* `description` + +Description text of the webhook. +* `url` + +The URL of the webhook endpoint. +* `url_params` + +Query parameters to append to the endpoint URL. +* `events` + +Events subscribed to the webhook. In the current release, ThoughtSpot supports only the `LIVEBOARD_SCHEDULE` event. +* `authentication` + +Authentication method and credentials that ThoughtSpot will use when sending HTTP requests to the webhook endpoint +* `signature_verification` + +Signature verification parameters for the webhook endpoint to verify the authenticity of incoming requests. + +===== Example request + +The following example shows the request body for updating the name, description text, and endpoint URL of a webhook object: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/webhook-lb-test/update' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "name": "webhook-lb-event", + "description": "Webhook for Liveboard schedule event", + "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d/2e5251b2-8274-41f6-80a0-1b82854df31f", + "events": [ + "LIVEBOARD_SCHEDULE" + ] +}' +---- + +===== Example response + +If the API request is successful, the API returns a 204 response code indicating a successful operation. + +==== Delete a webhook + +To delete a webhook, send a `POST` request to the `/api/rest/2.0/webhooks/delete` endpoint. + +===== Request parameters +Specify the name or ID of the webhook to delete. + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter|Description +|`webhook_identifiers` |__Array of strings__. ID of name of the webhooks to delete. +|| +|===== + +===== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/delete' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "webhook_identifiers": [ + "webhook-lb-test" + ] +}' +---- + +===== Example response + +If the API request is successful, the webhook is deleted, and the API returns the details of the deleted webhook in the response body. + +[source,JSON] +---- +{ + "deleted_count": 1, + "failed_count": 0, + "deleted_webhooks": [ + { + "id": "45fe7810-3239-4761-94fd-04c017df29c4", + "name": "webhook-test", + "description": "Webhook for testing purposes", + "org": { + "id": "1574427524", + "name": "testOrg2025" + }, + "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d/2e5251b2-8274-41f6-80a0-1b82854df31f", + "url_params": null, + "events": [ + "LIVEBOARD_SCHEDULE" + ], + "authentication": null, + "signature_verification": null, + "creation_time_in_millis": 1761184185887, + "modification_time_in_millis": 1761184185887, + "created_by": { + "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "name": "UserA@thoughtspot.com" + }, + "last_modified_by": null + } + ], + "failed_webhooks": [] +} +---- + +=== Verify the webhook payload + +After a webhook channel is configured for Liveboard schedule events and a webhook is created for these events at the Org level, it's applied to all Liveboard schedules in an Org. + +When a Liveboard schedule event is triggered based on the conditions defined in the schedule, the webhook sends the payload with the following schema to the configured endpoint. Based on the Liveboard job settings, the payload includes metadata properties such as webhook communication channel ID, recipient details, Liveboard schedule details, event properties, and a link to the Liveboard. + +For testing purposes, you can use a URL from the link:https://webhook.site/[Webhook site, window=_blank] as a webhook endpoint and check the payload when the Liveboard schedule event is triggered. + +==== Contents of the webhook playload + +The Webhook payload uses a specific schema structure that determines the contents of the payload delivered to the webhook endpoint. The payload contains metadata about the event, the source, the actor, the target object, and event-specific data. The payload is typically sent as a form field named `payload` in a `multipart/form-data` request, with optional file attachments. + +For more information about the schema structure, refer to the following sections. + +===== WebhookResponse +The `WebhookResponse` schema defines the standard response from webhook endpoints, confirming the webhook receipt and processing status. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|===== +| Field | Type | Description | Required? +| `status` | string | Status of the webhook payload processing. | Yes +| `message` | string | Message text about the result. For example, `Webhook received successfully`. | Yes +| `time` | string | Timestamp when the response was generated. | Yes +|||| +|===== + +===== WebhookPayload + +The `WebhookPayload` schema defines the structure for webhook event notifications, including event metadata, source, actor, target object, and event-specific data. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|===== +| Field | Type | Description | Required? + +| `eventId` | string | ID of each webhook event. For example, `n.820c00f9-d7ef-48e9-ab08-2ec1a48de0ab`. | Yes +| `timestamp` | string | Timestamp of when the event occurred. | Yes +| `eventType` | string | Type of event that triggered the webhook payload. For example, `LIVEBOARD_SCHEDULE`. | Yes +| `schemaVersion` | string | Schema version. | Yes +| `source` | object |Source endpoint that triggered the event. Includes the parameters defined in the xref:webhooks-lb-schedule.adoc#_webhooksourceinfo[WebhookSourceInfo] schema. | Yes +| `actor` | object | Actor that initiated the event. For more information, see xref:webhooks-lb-schedule.adoc#_webhookactorinfo[WebhookActorInfo]. | Yes +| `metadataObject` | object | Metadata object details. For more information, see xref:webhooks-lb-schedule.adoc#_webhooktargetobjectinfo[WebhookTargetObjectInfo]. | Yes +| `data` | object |Data specific to the Liveboard schedule event. For more information, see xref:webhooks-lb-schedule.adoc#_liveboardscheduledata[LiveboardScheduleData]. | Yes +|||| +|===== + +===== WebhookSourceInfo + +The `WebhookSourceInfo` schema defines the properties of source application instance that triggered the webhook event. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|===== +| Field | Type | Description | Required? + +| `applicationName` | string | Application name. For example, ThoughtSpot. | Yes +| `applicationUrl` | string | The URL of the ThoughtSpot application instance. | Yes +| `instanceId` | string | ID of the ThoughtSpot instance that triggered the payload. | Yes +| `orgId` | string | ID of the Org context in ThoughtSpot from which the event payload is triggered.| Yes +|||| +|===== + +===== WebhookActorInfo + +The `WebhookActorInfo` schema defines the properties of the entity that initiated the event. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|===== +| Field | Type | Description | Required? + +| `actorType` | string | Initiator of the event such as the API client or user. The default actor type is `SYSTEM`. | Yes +| `id` | string a| Unique identifier such as GUID or object ID).For system-generated responses, the `id` will be set as `null`. | No +| `name` | string a| Name of the actor that initiated the event. For system-generated responses, the `name` will be set as `null`. | No +| `email` | string a| Email of the actor that initiated the event. For system-generated responses, the `name` will be set as `null`. | No +|||| +|===== + +===== WebhookTargetObjectInfo + +The `WebhookTargetObjectInfo` schema defines the object for which the event is generated. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|===== +| Field | Type | Description | Required? + +| `objectType` | string | Type of object. For Liveboard schedule events, the object will be `LIVEBOARD`. | Yes +| `id` | string | Unique identifier of the Liveboard. | Yes +| `name` | string | Name of the Liveboard. | Yes +| `url` | string | Link to the object in the ThoughtSpot application. | No +|||| +|===== + +===== LiveboardScheduleData + +The `WebhookTargetObjectInfo` schema defines event-specific data for Liveboard schedule events, including schedule details, recipients, and additional context. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|===== +| Field | Type | Description | Required + +| `scheduleDetails` | object | Details of the Liveboard schedule that triggered the event. This includes the schedule ID, object type, and output format. For more information, see xref:webhooks-lb-schedule.adoc#_scheduledetails[ScheduleDetails]. | Yes +| `recipients` | array | Details of the ThoughtSpot users, groups, and email addresses of the external users who are configured as subscribers of the Liveboard schedule notifications and recipients of the webhook payload. For more information, xref:webhooks-lb-schedule.adoc#_recipientinfo[RecipientInfo]. | Yes +| `viewInfo` | object | Information about the Liveboard view. Applicable if the Liveboard Schedule event is triggered for a personalized view of the Liveboard. For more information, xref:webhooks-lb-schedule.adoc#_viewinfo[ViewInfo]. | No +| `aiHighlights` | string | AI Highlights information. Applicable if AI highlights feature is enabled for the visualizations on the Liveboard. | No +| `msgUniqueId` | string | Unique message identifier. Unique ID of the webhook payload message. This ID can be used for traceability and deduplication on the receiving end. | No +| `channelID` | string | The communication channel ID used for event dissemination. | No +| `channelType` | string | Type of the communication channel. The channel type used for webhook payloads is `webhook`. | No +| `communicationType` | string | Type of the messaging event. For Liveboard schedule events, the communication type will be `LiveboardSchedules`. | No +|||| +|===== + +===== ScheduleDetails + +The `ScheduleDetails` schema defines the properties of the schedule that triggered the event, metadata, author, and export request. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|==== +| Field | Type | Description | Required? +| `scheduleId` | string | ID of the Liveboard schedule. | Yes +| `name` | string | Name of the Liveboard schedule. | Yes +| `creationTime` | string | Timestamp of when the schedule was created. | No +| `description` | string | Description of the schedule. | No +| `authorId` | string | ID of the user that scheduled the Liveboard job. | No +| `viewInfo` | object | Information about the Liveboard view. Applicable if the Liveboard Schedule event is triggered for a personalized view of the Liveboard. For more information, xref:webhooks-lb-schedule.adoc#_viewinfo[ViewInfo]. | No +| `userIds` | array | IDs of the ThoughtSpot users that are subscribed to the scheduled Liveboard notifications. | No +| `groupIds` | array | IDs of the ThoughtSpot groups that are subscribed to the scheduled Liveboard notifications.| No +| `runId` | string | Schedule run ID of the Liveboard job. | No +| `exportRequest` | object | Details of the file export request. If the scheduled notification includes PDF attachment, the `exportRequest` includes details of the Liveboard and PDF page attributes. | No +| `fileFormat` | string | File format for export. The schedule notification generally include PDF attachments. | No +| `status` | string | Status of the schedule. | No +| `emailIds` | array | Email IDs of users subscribed to Liveboard job schedule. | No +|||| +|==== + +===== RecipientInfo + +The `RecipientInfo` schema defines the object properties of the recipients of the scheduled notifications. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|===== +| Field | Type | Description | Required? + +|`type` | string a| Type of recipient. Valid types are: + +* `USER` - For ThoughtSpot users +* `EXTERNAL_EMAIL` - For external recipients | Yes + +| `id` | string | IDs of the ThoughtSpot user and groups that are subscribed to the Liveboard schedule. | No +| `name` | string | Name of the recipient. | No +| `email` | string | Email address of the recipient. | Yes +| `locale`| string | Locale of the recipient. For example, `en_US`. | No +|||| +|===== + + +===== ViewInfo + +The `ViewInfo` schema defines properties of the Liveboard view for which the event is generated. + +[width="100%" cols="1,1,3,1"] +[options='header'] +|====== +| Field | Type | Description | Required? + +| `viewId` | string | ID of the Liveboard personalized view. | Yes +| `viewName` | string | Name of the Liveboard personalized view. | Yes +|||| +|====== + +==== JSON payload example + +[source,JSON] +---- +{ + "eventId": "n.18bd8bd5-dee3-4d5c-918e-aec3ba1a090f", + "timestamp": "2025-08-29T09:25:32Z", + "eventType": "LIVEBOARD_SCHEDULE", + "schemaVersion": "1.0", + "source": { + "applicationName": "ThoughtSpot", + "applicationUrl": "https://my.thoughtspot.cloud", + "instanceId": "3d85f2fe-8489-11f0-bdf8-5ba90", + "orgId": "2100019165" + }, + "actor": { + "actorType": "SYSTEM" + }, + "metadataObject": { + "objectType": "LIVEBOARD", + "id": "c30a0d49-5747-475d-8985-e975b1c2cf6d", + "name": "Sample Liveboard (View: sample view name)", + "url": "https://my.thoughtspot.cloud/?utm_source=scheduled-pinboard&utm_medium=email#/pinboard/c30a0d49-5747-475d-8985-e975b1c2cf6d?view=a8118b21-4581-4315-8833-39b2aa5be542" + }, + "data": { + "scheduleDetails": { + "scheduleId": "cffddca8-d4fc-4575-b8ec-a50e696ccdfc", + "name": "Sample Liveboard", + "creationTime": "2025-08-29T07:52:23Z", + "description": "Daily sales performance report", + "authorId": "59481331-ee53-42be-a548-bd87be6ddd4a", + "viewInfo": { + "viewId": "a8118b21-4581-4315-8833-39b2aa5be542", + "viewName": "sample view name" + }, + "userIds": ["59481331-ee53-42be-a548-bd87be6ddd4a"], + "groupIds": [], + "runId": "29001ffd-6a84-45cd-a957-621fce89afc6", + "exportRequest": { + "object_type": "LIVEBOARD", + "pdf_params": { + "orientation": "LANDSCAPE", + "page_size": "A4" + }, + "liveboard_params": { + "layout_type": "VISUALIZATION", + "personalised_view_id": "a8118b21-4581-4315-8833-39b2aa5be542", + "liveboard_viz_selection": { + "complete_liveboard": false, + "included_viz_id": [ + "efe80e30-ca82-4b83-a9c0-7371be45d3e6", + "957c9e37-0352-40ca-8d07-fb056a91332d" + ] + }, + "print_document_params": { + "include_cover_page": true, + "include_filter_page": true, + "pageFooterParams": { + "include_logo": true, + "include_page_number": true, + "text": "footer" + } + }, + "visualization_format_options": { + "truncate_tables": true + } + }, + "request_type": "SCHEDULE" + }, + "fileFormat": "pdf", + "status": "SCHEDULED", + "emailIds": [] + }, + "recipients": [ + { + "type": "USER", + "id": "user-123", + "name": "John Doe", + "email": "john@company.com", + "locale": "en_US" + } + ], + "viewInfo": { + "viewId": "a8118b21-4581-4315-8833-39b2aa5be542", + "viewName": "sample view name" + }, + "aiHighlights": "Sales increased by 15% compared to last quarter", + "msgUniqueId": "2f31df6a-2623-4953-a9bb-5af9b2922474", + "channelID": "6dfa4d82-fdc8-4d5b-8294-a5de0dd5ede1", + "channelType": "webhook", + "communicationType": "LiveboardSchedules" + } +} +---- + +//// + +As shown in the preceding example, the JSON payload includes the following content: + +* `actor` + +Initiator of the event. The actor type can be `USER`, `SYSTEM`, or `API_CLIENT`. +* `channelID` + +The communication channel ID used for event dissemination. +* `channelType` + +Type of the communication channel. The channel type used for webhook payloads is `webhook`. +* `communicationType` + +Type of the messaging event. For Liveboard schedule events, the communication type will be `LiveboardSchedules`. +* `MyUniqueID` + +Unique ID of the webhook payload. This ID can be used for traceability and deduplication on the receiving end. +* `recipients` + +Details of the ThoughtSpot users, groups, and email addresses of the external users who are configured as subscribers of the Liveboard schedule notifications and recipients of the webhook payload. +* `scheduleDetails` + +Details of the Liveboard schedule that triggered the event. This includes the schedule ID, object type, and output format. If the Liveboard job is configured to send data as a downloadable PDF, the file format will be set as `PDF`. +* `eventID` and `eventType` + +The ID and type of the event. For Liveboard schedule events, the type is `LIVEBOARD_SCHEDULE`. +* `metadataObject` + +Details of the Liveboard object. +* `schemaVersion` + +Schema version of the payload. +* `timestamp` + +Timestamp of when the event occurred. +* `source` + +Source of the webhook payload trigger. This includes the ThoughtSpot application name, URL, instance ID, and the ID of the Org context in ThoughtSpot. + +Along with the JSON payload, if the Liveboard schedule is configured to send a PDF version of the Liveboard, a PDF attachment will be included in the payload. + + +===== Example WebhookPayload + +[source,json] +---- +{ + "eventId": "n.18bd8bd5-dee3-4d5c-918e-aec3ba1a090f", + "timestamp": "2025-08-29T09:25:32Z", + "eventType": "LIVEBOARD_SCHEDULE", + "schemaVersion": "1.0", + "source": { + "applicationName": "ThoughtSpot", + "applicationUrl": "https://my.thoughtspot.cloud", + "instanceId": "3d85f2fe-8489-11f0-bdf8-5ba90", + "orgId": "0" + }, + "actor": { + "actorType": "SYSTEM" + }, + "metadataObject": { + "objectType": "LIVEBOARD", + "id": "c30a0d49-5747-475d-8985-e975b1c2cf6d", + "name": "Sample Liveboard (View: sample view name)", + "url": "https://my.thoughtspot.cloud/?utm_source=scheduled-pinboard&utm_medium=email#/pinboard/c30a0d49-5747-475d-8985-e975b1c2cf6d?view=a8118b21-4581-4315-8833-39b2aa5be542" + }, + "data": { + "scheduleDetails": { + "scheduleId": "cffddca8-d4fc-4575-b8ec-a50e696ccdfc", + "name": "Sample Liveboard", + "creationTime": "2025-08-29T07:52:23Z", + "description": "Daily sales performance report", + "authorId": "59481331-ee53-42be-a548-bd87be6ddd4a", + "viewInfo": { + "viewId": "a8118b21-4581-4315-8833-39b2aa5be542", + "viewName": "sample view name" + }, + "userIds": ["59481331-ee53-42be-a548-bd87be6ddd4a"], + "groupIds": [], + "runId": "29001ffd-6a84-45cd-a957-621fce89afc6", + "exportRequest": { + "object_type": "LIVEBOARD", + "pdf_params": { + "orientation": "LANDSCAPE", + "page_size": "A4" + }, + "liveboard_params": { + "layout_type": "VISUALIZATION", + "personalised_view_id": "a8118b21-4581-4315-8833-39b2aa5be542", + "liveboard_viz_selection": { + "complete_liveboard": false, + "included_viz_id": [ + "efe80e30-ca82-4b83-a9c0-7371be45d3e6", + "957c9e37-0352-40ca-8d07-fb056a91332d" + ] + }, + "print_document_params": { + "include_cover_page": true, + "include_filter_page": true, + "pageFooterParams": { + "include_logo": true, + "include_page_number": true, + "text": "footer" + } + }, + "visualization_format_options": { + "truncate_tables": true + } + }, + "request_type": "SCHEDULE" + }, + "fileFormat": "pdf", + "status": "SCHEDULED", + "emailIds": [] + }, + "recipients": [ + { + "type": "USER", + "id": "user-123", + "name": "John Doe", + "email": "john@company.com", + "locale": "en_US" + } + ], + "viewInfo": { + "viewId": "a8118b21-4581-4315-8833-39b2aa5be542", + "viewName": "sample view name" + }, + "aiHighlights": "Sales increased by 15% compared to last quarter", + "msgUniqueId": "2f31df6a-2623-4953-a9bb-5af9b2922474", + "channelID": "6dfa4d82-fdc8-4d5b-8294-a5de0dd5ede1", + "channelType": "webhook", + "communicationType": "LiveboardSchedules" + } +} +---- +//// +==== File attachments + +The payload also includes file attachments in the file format specified in the Liveboard schedule. The file format can be PDF, CSV, or XLSX. + +== Additional resources + +* link:https://docs.thoughtspot.com/cloud/latest/liveboard-schedule[Scheduling Liveboard jobs, window=_blank] +* +++Liveboard schedule REST APIs+++ + + + + diff --git a/modules/ROOT/pages/webhooks.adoc b/modules/ROOT/pages/webhooks.adoc index 7b751e19d..428635ae8 100644 --- a/modules/ROOT/pages/webhooks.adoc +++ b/modules/ROOT/pages/webhooks.adoc @@ -1,309 +1,19 @@ -= Webhooks for KPI monitor alerts += Webhooks :toc: true -:page-title: Webhooks for KPI Monitor alerts +:page-title: Webhooks :page-pageid: webhooks -:page-description: Register a Webook to send KPI monitor alerts to an external application +:page-description: Register a Webook to send KPI monitor and Liveboard schedule alerts to an external application -ThoughtSpot users with administrator or developer privileges can register a Webhook to send Monitor alerts from a Key Performance Indicator (KPI) chart to an external application. KPI Monitor alerts notify users when a KPI metric meets a threshold condition or periodically as per the schedule configured by the user. +Webhooks in ThoughtSpot provide a way to automate workflows and integrate with external systems by sending real-time notifications when specific events occur. In ThoughtSpot, webhooks can be used for two primary alerting use cases: -For example, you can create an alert to be notified when a Sales KPI exceeds a threshold of 200,000, or when -your weekly sales increase by 2%. By default, the email notifications are sent to the alert subscriber’s email address. With Webhooks, you can trigger alerts to the REST endpoint of an external application via HTTP POST requests and customize your application workflow to present these alerts as SMS messages or Slack notifications. +* KPI alerts + +For KPI charts in a Liveboard or Answer, ThoughtSpot allows creating and scheduling alerts. KPI Monitor alerts notify users when a KPI metric meets a threshold condition or periodically as per the schedule configured by the user. To send these alerts and notify external applications when a KPI meets a defined threshold, changes value, or on a scheduled basis, ThoughtSpot provides webhooks. +This allows organizations to initiate actions in third-party applications, such as sending notifications to Slack, Microsoft Teams, or custom business systems, or triggering automated workflows such as order placements when inventory levels drop below a set value. + +For more information, see xref:webhooks-kpi-alerts.adoc[Webhooks for KPI monitor alerts]. -//// - -[NOTE] -==== -The Webhooks feature is in Beta and is turned off by default. To enable this feature on your instance, contact ThoughtSpot Support. -==== -//// - -== Before you begin - -* Make sure your ThoughtSpot user account has the privileges required to access the *Develop* page in the ThoughtSpot UI. -* Your destination application has a callback URL to accept HTTP POST requests. -* If you plan to use OAuth authentication, make sure you have the OAuth credentials and authorization URL of your application -* If you plan to use an API key for authentication, ensure that you have a valid API key. - -== Configure Webhooks -To configure a Webhook and send alert data to the destination URL, complete the following steps: - -* xref:webhooks.adoc#_register_a_webhook[Register a Webhook in ThoughtSpot] -* xref:webhooks.adoc#_assign_webhook_to_a_kpi_monitor_alert[Assign the registered Webhook to KPI Monitor alerts] - -=== Register a Webhook - -To register a Webhook in ThoughtSpot, complete the following steps: - -. Go to **Develop** > **Customizations** > **Webhooks**. -+ -If you are using the new experience, the *Developer* will be in the Application switcher image:./images/app_switcher.png[the app switcher menu]. - -. Click **Create Webhook**. -. In the ** Create Webhook** modal, specify the Webhook name and the URL of the destination application. -+ -For testing purposes, you can use a URL from the link:https://webhook.site/[Webhook site, window=_blank]. -. Specify the authentication type. -* No authentication + -Default authentication option. Not recommended for production environments. - -* API Key + -Allows using an API key to authenticate API requests to the destination URL. Specify the API key to use in the `X-API-Key` request header. - -* OAuthentication 2.0 + -Allows using OAuth credentials to authorize API requests. Specify client ID, client secret key, and authorization URL. -If the registered Webhook has Oauth authentication enabled, `Authorization: Bearer ` is sent in the request header. -. If the destination URL requires query parameters to be passed in the request URL, specify the parameters as key-value pairs. -. Click **Save**. - -=== Assign Webhook to a KPI Monitor alert - -To assign the registered Webhook to an alert: - -* Go to a KPI chart and click the **Create alert** icon. + -If the alert is already configured, go to **Monitor** and click Edit alert to modify the alert properties. -* In the alert configuration modal, go to **Select notification channel** and select **Custom channel** and the Webhook. -* Ensure that alert type and subscription details are defined. -* Click **Save**. + -Based on the type of alert, the notification payload will be sent in JSON format to the Webhook URL via HTTP POST request. - -The following example shows the notification payload: - -[source,JSON] ----- -{ - "data": { - "currentUser": { - "displayName": "Guest 1", - "email": "guest1@thoughtspot.com" - }, - "schemaVersion": "v1", - "schemaType": "MONITOR", - "notificationType": "UPDATION", - "updationWebhookNotification": { - "modifyUrl": "", - "monitorRuleForWebhook": { - "scheduleString": "hourly every hour ", - "metricName": "Total Revenue Trend", - "alertType": "Scheduled", - "metricId": { - "pinboardVizId": { - "pinboardId": "22a8f618-0b4f-4401-92db-ba029ee13486", - "vizId": "ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb" - } - }, - "metricUrl": "http://{ThoughtSpot-Host}/?utm_source=kpi_monitor&utm_medium=webhook/#/pinboard/22a8f618-0b4f-4401-92db-ba029ee13486/ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb", - "ruleName": "Alert on Total Revenue Trend", - "conditionString": "", - "ruleId": "a4b0a1f4-279d-42ab-a710-4ba6964869fa" - }, - "unsubscribeUrl": "http://{ThoughtSpot-Host}/?utm_source=kpi_monitor&utm_medium=webhook/#/pinboard/22a8f618-0b4f-4401-92db-ba029ee13486/ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb?ts-type=unsubscribeFromRule&ts-ruleid=a4b0a1f4-279d-42ab-a710-4ba6964869fa" - } - } -} ----- - -== Webhook schema -The following Webhook schema is used when sending an HTTP POST request body to the registered Webhook URL: - ----- -WebhookNotification { - enum SchemaVersion, - enum EventSchemaType, - enum NotificationType, - User CurrentUser, - DeletionWebhookNotification deletionWebhookNotification, - FailureWebhookNotification failureWebhookNotification, - ScheduledMetricUpdateWebhookNotification scheduledMetricUpdateWebhookNotification, - SelfSubscriptionWebhookNotification selfSubscriptionWebhookNotification, - SubscriptionWebhookNotification subscriptionWebhookNotification, - ThresholdReachedMetricUpdateWebhookNotification thresholdReachedMetricUpdateWebhookNotification, - UpdationWebhookNotification updationWebhookNotification, -} ----- - -The fields are populated according to the notification type. For all types of notifications, the following four fields are populated: - -* SchemaVersion + -The version of the schema used + -+ ----- -enum SchemaVersion { - v1, -} ----- -* EventSchemaType + -Type of the schema used -+ ----- -enum EventSchemaType { - MONITOR, -} ----- -* NotificationType + -Type of the monitor notification sent -+ ----- -enum NotificationType { - SELF_SUBSCRIPTION, - DELETION, - UPDATION, - FAILURE, - SUBSCRIPTION, - SCHEDULE_METRIC_UPDATE, - THRESHOLD_METRIC_UPDATE, -} ----- -* CurrentUser + -User for which the notification is sent. -+ ----- -User { - String id, - String displayName, - String email, -} ----- - -Conditional fields include: - -* DeletionWebhookNotification deletionWebhookNotification + -Populated only when notificationType is DELETION. -* FailureWebhookNotification failureWebhookNotification + -Populated only when notificationType is FAILURE. -* ScheduledMetricUpdateWebhookNotification scheduledMetricUpdateWebhookNotification, + -Populated only when notificationType is SCHEDULE_METRIC_UPDATE. -* SelfSubscriptionWebhookNotification selfSubscriptionWebhookNotification, + -Populated only when notificationType is SELF_SUBSCRIPTION. -* SubscriptionWebhookNotification subscriptionWebhookNotification, + -Populated only when notificationType is SUBSCRIPTION. -* ThresholdReachedMetricUpdateWebhookNotification thresholdReachedMetricUpdateWebhookNotification, + -Populated only when notificationType is THRESHOLD_METRIC_UPDATE. -* UpdationWebhookNotification updationWebhookNotification + -Populated only when notificationType is UPDATION. - -The following examples show the schema for different alert notification types: - -=== Scheduled alert notification - -A scheduled alert is sent as per the configured periodicity. - -The following schema is used in the notification sent for scheduled alerts: ----- -ScheduledMetricUpdateWebhookNotification { - MonitorRuleForWebhook monitorRuleForWebhook, - String modifyUrl, - String unsubscribeUrl, - RuleExecutionDetails ruleExecutionDetails, -} ----- - -The following example shows the email notification for a scheduled alert: - -[.bordered] -image::./images/scheduledAlert.png[Scheduled alert] - -=== Threshold alert notification - -A threshold alert is sent when a metric in the KPI chart reaches the configured threshold. - -The following schema is used in the notification sent for threshold alerts: ----- -ThresholdReachedMetricUpdateWebhookNotification { - MonitorRuleForWebhook monitorRuleForWebhook, - String modifyUrl, - String unsubscribeUrl, - RuleExecutionDetails ruleExecutionDetails, -} ----- - -The following example shows the email notification for a threshold alert: - -[.bordered] -image::./images/thersholdAlert.png[threshold alert] - -=== SelfSubscription notification - -A self-subscription notification is sent for alerts self-subscribed by a user. - -The following schema is used in the notification sent for self-subscribed notifications: - ----- -SelfSubscriptionWebhookNotification { - MonitorRuleForWebhook monitorRuleForWebhook, - String modifyUrl, - String unsubscribeUrl, - RuleExecutionDetails ruleExecutionDetails, -} ----- - -The following example shows the email notification sent for a self-subscribed alert: - -[.bordered] -image::./images/userSubscribedAlert.png[User subscribed alert] - -=== Subscription notifications - -A subscription notification is sent when a user subscribes to a notification. - -The following schema is used in the subscription notification: - ----- -SubscriptionWebhookNotification { - MonitorRuleForWebhook monitorRuleForWebhook, - String modifyUrl, - String unsubscribeUrl, - RuleExecutionDetails ruleExecutionDetails, - User subscribedByUser, -} ----- - -The following example shows the email notification sent from ThoughSpot after a user subscribes to an alert: - -image::./images/subscriptionAlert.png[User subscribed alert] - -=== Delete Webhook notification - -A delete notification is sent to subscribers when an alert they subscribed to is deleted in ThoughtSpot. - -The following schema is used in the notification sent when an alert is deleted: - ----- -DeletionWebhookNotification { - String ruleName, - String metricName, - MetricId metricId, - User deletedByUser, -} ----- - -The following example shows the email notification sent to the subscribers when an alert is deleted: - -[.bordered] -image::./images/deleteAlert.png[delete webhook notification] - -=== Failure Webhook notification - -A failure notification is sent to subscribers when an alert execution fails. - -The following schema is used in the notification sent when a Webhook alert fails: - ----- -FailureWebhookNotification { - MonitorRuleForWebhook monitorRuleForWebhook, - String modifyUrl, - String unsubscribeUrl, - String reason, -} ----- - -The following example shows the email notification sent to the subscribers when an alert execution fails: - -[.bordered] -image::./images/failureAlert.png[Webhook failure notification] - -== Additional references - -* link:https://docs.thoughtspot.com/cloud/latest/monitor[Monitor alerts documentation, window=_blank] +* Liveboard schedule alerts [beta betaBackground]^Beta^ + +Starting with 10.14.0.cl, ThoughtSpot supports using webhooks to send real-time notifications to external applications and communication channels when a Liveboard scheduled job is triggered. This enables you to automate workflows, send custom notifications, or integrate with other systems. To enable this feature, contact ThoughtSpot Support. + +For information about how to configure communication channels and webhooks, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 36e4fb5d5..6860aefbb 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,50 @@ This page lists new features, enhancements, and deprecated functionality in ThoughtSpot Embedded instances. +== Version 10.14.0.cl + +=== Code based custom actions +ThoughtSpot now enables developers to define custom action in their embed code through the Visual Embed SDK. This enhancement enables code based customization of actions for Liveboards, Visualizations, Answers, and Spotter. With this functionality, developers can add custom actions that show up as new menu options in one of the following UI elements: + +* the primary menu bar +* the **More** options menu image:./images/icon-more-10px.png[the more options menu] +* the contextual menu that appears when a user right-clicks on an Answer or visualization + + +Code based custom actions are flexible across Orgs and groups as well. + +For more information, see xref:code-based-custom-actions.adoc[Code based custom actions] + +=== Webhooks for Liveboard schedule events [beta betaBackground]^Beta^ + +You can now configure a xref:webhooks-lb-schedule.adoc[webhook for Liveboard schedule events] to automate notifications to external applications. This feature allows you to send Liveboard reports directly to a webhook endpoint, such as your internal marketing or incident management app, at a scheduled frequency. It eliminates the need to manually process data from email notifications and gives you full control over how the data is handled in your downstream workflows. + +This feature is currently in beta and is not enabled by default. To enable it on your instance, contact ThoughtSpot Support + +=== Template variables for publishing +You can now configure formula variables and assign these variables to your metadata. The variable APIs also include several enhancements to streamline variable creation and update workflows. + +For more information, see xref:variables.adoc[Variables documentation]. + + +=== Parameter chip visibility configuration + +The `HostEvent.UpdateParameters` event now includes an `isVisibleToUser` flag to control the visibility of Parameter chips on embedded ThoughtSpot pages. + +Previously, the Parameter chip displaying behavior was inconsistent, because some embed types would keep the chips visible via an override using `HostEvent.UpdateParameters`, while other embed types would hide the chips when the Parameter is overridden. With the new enhancement, the `isVisibleToUser` attribute in `HostEvent.UpdateParameters` is set to `false` by default for all pages, to ensure consistent behavior. + +Impact on your current implementation:: +With the new enhancement, the embedded pages that previously kept the parameter visible after an override via `HostEvent.UpdateParameters`, will now hide it unless the `isVisibleToUser` attribute is explicitly set to `true`. This new behavior introduces a breaking change for any implementation relying on the previous default chip visibility behavior. + +Recommended action:: +Developers who want to retain the old behavior must update their integration to pass the `isVisibleToUser: true` setting when updating Parameters via `HostEvent.UpdateParameters`. + +=== Visual Embed SDK + +For information about the new features and enhancements introduced in Visual Embed SDK version 1.43.0, see xref:api-changelog.adoc[Visual Embed changelog]. + +=== REST API +For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + == Version 10.13.0.cl === Spotter AI APIs diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index e376d7e95..57cffd8ba 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -34,10 +34,16 @@ module.exports = { DEV: 'dev', }, VERSION_DROPDOWN: [ + { + label: '10.14.0.cl', + link: ' ', + subLabel: 'Cloud (Latest)', + }, { label: '10.13.0.cl', link: ' ', subLabel: 'Cloud (Latest)', + iframeUrl: 'https://developer-docs-10-13-0-cl.vercel.app/docs/', }, { label: '10.12.0.cl',