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..7dd9e8b18 --- /dev/null +++ b/modules/ROOT/pages/code-based-custom-actions.adoc @@ -0,0 +1,448 @@ += 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 entirely within their code base, 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..085e0e5b4 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,79 @@ 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 + +Model columns +|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|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/prerender.adoc b/modules/ROOT/pages/prerender.adoc index dce03679f..32b4035d5 100644 --- a/modules/ROOT/pages/prerender.adoc +++ b/modules/ROOT/pages/prerender.adoc @@ -1,290 +1,324 @@ -= Prerender components += Pre-rendering ThoughtSpot Embed components :toc: true -:toclevels: 3 +:toclevels: 2 -:page-title: Prerender components +:page-title: Pre-rendering for Fast Embeds :page-pageid: prerender -:page-description: Prerender components to optimize user experience of your embedding application +:page-description: How to use pre-rendering to optimize performance and user experience in ThoughtSpot embedding -To optimize your user's experience when ThoughtSpot is embedded into your application, we recommend using the prerender method. +Before implementing pre-rendering, let's understand how embedding ThoughtSpot works in a typical web app. -== Prerender +== How embedding works -You can load ThoughtSpot components that are not specific to the user's session before your application user accesses the embedded content. With this, the amount of ThoughtSpot assets left to load when the user accesses the embedded content is reduced. +ThoughtSpot is a web app, and like any modern web application, it requires two main things to function: -=== When to use prerender +* *Assets* - The static files your browser needs to display and run the application, such as JavaScript files, CSS files, fonts, and images. +* *API Calls*: These are network requests made from the browser to the ThoughtSpot backend to fetch: + +- Data (the actual analytics, tables, charts, and so on) +- Metadata (information about users, tables, permissions, and so on) -Use prerender in the following cases: +image::./images/pre-render/web-app.png[] -* if you have applications that do not have ThoughtSpot on the landing page. -* if you are embedding ThoughtSpot Liveboards in your applications. +When you embed ThoughtSpot into your application, the browser must first download all required assets. Once these assets are loaded, the application executes its JavaScript code, which then initiates API calls to fetch the data and metadata necessary to render analytics for the user. -=== How it works +== How ThoughtSpot optimizes asset and API loading -Pre-render allows developers to pre-load the ThoughtSpot application in the background before the user navigates to the embedded content. +ThoughtSpot internally optimizes the loading process by splitting assets and API calls, so that only the files and data needed for a specific component are loaded when required. This means: -It allows you to create a placeholder element on the page for the Liveboard to eventually populate. To preload components, you must place this element into a section of your application that will be viewed before the Liveboard. For example, it is common for analytics applications to have a custom-built landing page that directs users to relevant pieces of embedded content. This would be an ideal place to preload the component, so the frame is ready to render by the time the user clicks on a specific link. +- For embed components such as Search, Liveboard, and Spotter, only the assets and API calls required for that component are loaded. +- There are a few common assets such as fonts, shared JavaScript, CSS, and common API calls to fetch user information, that are always loaded, as they are used across all embed types. +- In addition to these common resources, each component (for example, Liveboard) will load its own specific JavaScript, CSS, and make API calls only needed for that component. -The following figure illustrates the benefits of the pre-render method: +image::./images/pre-render/asset-split.png[] -image::./images/prerender.png[prerender] +For example, if you are embedding a Liveboard: -=== How to implement prerender +. The browser first loads the common assets and makes common API calls for resources such as fonts and user information. +. Then, it loads the Liveboard-specific JavaScript and CSS files, and make the necessary API calls to fetch Liveboard data. +. Assets and API calls for other components, such as Search or Spotter, are not loaded unless those components are actually used. -Depending on the framework and project, you can implement this using xref:_standard_js[Standard JavaScript] or xref:_react[React]. +This approach ensures that the embed is efficient, loading only what is necessary for the user's current experience, and helps improve performance by reducing unnecessary downloads and network requests. -==== Standard JS +Before getting started with pre-rendering, let’s understand the essential first step in embedding ThoughtSpot. -If using Javascript: +== `init` call -. Create a container for the Liveboard and a placeholder. -+ -For this approach, you require two containers: +In ThoughtSpot embedding, `init` is first essential step. Before you can render any ThoughtSpot embed component, you must call the `init` method from the Visual Embed SDK. This function initializes the SDK and sets up the connection to your ThoughtSpot instance. It is the required starting point for any embedding scenario. -* a `div` container with `absolute` position. This will eventually be used to render the Liveboard. -* a placeholder `div`. This is the container designated for the Liveboard, which you will set as the primary embed container in your application code. When it is time to load a Liveboard, move the prerender `div` on top of the placeholder `div`. +=== When should you call `init`? -+ -[source,HTML] ----- -
-
----- +Call `init` as early as possible in your application lifecycle, ideally on your app’s initial load, landing page, or loading screen. + +The `init` call is very lightweight; it does not trigger heavy asset downloads or make many API calls. Therefore, there is no downside to calling it early, and it ensures that subsequent embed loads are as fast as possible. + +image::./images/pre-render/init-flow.png[] + +[NOTE] +==== +Always call `init` before rendering any embed component, and do so as soon as your app loads. +==== + +== Pre-rendering overview + +Now that you know how ThoughtSpot loads assets and data, let’s explore how you can make the experience even faster for your users. + +Consider the scenario, where you have an app with a landing screen where users spend some time before navigating to the embedded ThoughtSpot page. In the current setup, ThoughtSpot only starts loading when the user actually visits the analytics page. What if you could start loading some of ThoughtSpot’s essential files and data while users are still on the landing screen, before they reach the analytics page? + +That’s exactly what pre-rendering does! By starting the load process early, you can make the analytics appear much faster when the user finally navigates to that page. + +image::./images/pre-render/pre-rendering-basic.png[] + +=== Terminology used in this guide + +Keeping the above in mind, let's define a few key terms that we'll use later in this guide: + +* **Common asset download** – The shared JavaScript and CSS files that every embed needs +* **Common API calls** – The basic API requests made for things like user info, used by all embed types +* **Embed level asset download** – The specific files (like JS and CSS) needed only for the embed type you're using (for example, Liveboard or Search) +* **Embed API calls** – The API requests made to fetch the actual data and content for the specific embed (like loading a Liveboard's data) +* **Host app** – This is your web application (the main app your users interact with) +* **Analytics page** – This is a page in your web app where ThoughtSpot is actually embedded + +== How to use pre-rendering? + +Based on your use case, you can choose to pre-render the embed in one of the following ways: + +. xref:prerender.adoc#_pre_render_with_liveboard_id[Pre-render with Liveboard ID] +. xref:prerender.adoc#_pre_render_without_the_liveboard_id[Pre-render without the Liveboard ID] +. xref:prerender.adoc#_pre_render_on_demand[Prerender on demand] +. xref:prerender.adoc#_normal_render[Normal render] +. xref:prerender.adoc#_prefetch_assets[Prefetch assets] + +=== Pre-render with Liveboard ID + +In this approach, you load everything all at once. When the user navigates to the analytics page, the embed is already loaded and ready to show. -+ -[source,HTML] +- Fully loads the embed iframe, including all assets and Liveboard data, as soon as the component is rendered. +- Fastest experience for a specific Liveboard. +- Maximum resource usage if the end user never views the embed. + +image::./images/pre-render/dig3_pre_with_livid.png[] + +==== Implementation + +In your application's home page, loading page, or landing page, you need to prerender the embed with the Liveboard ID. + +[source,JSX] ---- -#prerender{ - position: absolute; - opacity: 0; - left: 0; - top: 0; - height: 0; - width: 0; -} +// React + ---- -. PreRender ThoughtSpot -+ -Inside the prerender `div`, you can create a placeholder for Liveboard embedding. Before calling the Liveboard GUID, call `prerenderGeneric` to start the load process for the primary embed and transfer the bulk of the information needed by ThoughtSpot to the client browser. +OR -+ [source,JavaScript] ---- -let renderDiv = document.getElementById("prerender"); -let embed = new LiveboardEmbed(renderDiv, { - frameParams: { - height: "1200px" - } +// JavaScript +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; + +const embed = new LiveboardEmbed({ + liveboardId: 'e40c0727-01e6-49db-bb2f-5aa19661477b', + preRenderId: 'pre-render-with-liveboard-id', }); -embed.prerenderGeneric(); + +embed.preRender(); +---- + +When you actually want to show the Liveboard, call this component: + +[source,JSX] +---- +// React + ---- -. Render the embedded Liveboard -+ -When it is time for the user to view a specific liveboard, move the `prerender div` onto the placeholder, and instruct the Liveboard Embed to load the required content. To do this, use the `navigateToLiveboard` function on the embed object: +OR -+ [source,JavaScript] ---- -//Navigate embed container to new liveboard id - -let liveboardID = "16b8c2e2-edfc-4e42-8827-98387f384b1b" -embed.navigateToLiveboard(liveboardID) - -//Obtain the current bounds of the placeholder element -let placeholderDiv = document.getElementById("placeholder"); -const coords = placeholderDiv.getBoundingClientRect(); -const offset = getOffset(placeholderDiv); - -//Move the renderer into those bounds -renderDiv.style.opacity = 1; -renderDiv.style.top = offset.top + "px"; -renderDiv.style.left = offset.left + "px"; -renderDiv.style.width = coords.width + "px"; -renderDiv.style.height = coords.height + "px"; - -function getOffset(el) { - var _x = 0; - var _y = 0; - while (el && !isNaN(el.offsetLeft) && !isNaN(el.offsetTop)) { - _x += el.offsetLeft - el.scrollLeft; - _y += el.offsetTop - el.scrollTop; - el = el.offsetParent; - } - return { top: _y, left: _x }; -} +// JavaScript +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; + +const embed = new LiveboardEmbed({ + liveboardId: 'e40c0727-01e6-49db-bb2f-5aa19661477b', + preRenderId: 'pre-render-with-liveboard-id', +}); + +embed.render(); ---- -==== React +This approach is the fastest way to load the embed, but it is also the most resource-intensive. +The makes calls to the ThoughtSpot API to fetch the Liveboard data and metadata, which might be unwanted if the end user never views the embed. + +=== Pre-render without the Liveboard ID -If using React, make sure the container is not continuously reloaded with state changes. You can use a context provider to achieve this. For more information, see link:https://react.dev/learn/passing-data-deeply-with-context[https://react.dev/learn/passing-data-deeply-with-context, window=_blank]. +In this approach, you load the common assets and common API calls early, but you defer the Liveboard-specific data/API calls until needed. -[Source,TypeScript] +- Loads common assets and bootstrap logic early. +- Defers Liveboard-specific data/API calls until needed. +- Keeps the app ready, making the first Liveboard load faster. +- Still loads some assets even if the end user never opens the embed. + +image::./images/pre-render/dig4_wo_livid.png[] + +To use this strategy, place the following component on your application's home page, loading page, or landing page (before the end user navigates to the analytics): + +[source,JSX] ---- -const prerenderdLiveboardContext = createContext({}); + ---- -This approach requires two containers. The first is a `div` with absolute position. This will eventually be used to render the liveboard. +OR -The second is a placeholder. This is the container designated for the Liveboard, which you will set as the primary embed container in your application code. When loading the Liveboard, move the `prerender div` on top of the placeholder div. +[source,JavaScript] +---- +// JavaScript +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; -. Create render shell -+ -This is a `div` element with absolute position. Use context variables to control the div’s visibility and coordinate position. This div also holds the embedded Liveboard, and the `liveboardId` is set by the respective context variable. +const embed = new LiveboardEmbed({ + preRenderId: 'pre-render-without-liveboard-id', +}); -+ -By default, this `div` will be invisible and placed into a corner of the page (0 coordinates), with no `liveboardId`. +embed.preRender(); +---- -+ -[source,TypeScript] +When you actually want to show the Liveboard, call this component: + +[source,JSX] ---- -export const PrerenderedLiveboardShell = () => { - - const ref = useRef(null); - const lb = useRef(null); - const { isVisible, liveboardId, coords } = useContext( - prerenderdLiveboardContext - ); - - return ( -
- ); -} + ---- -. Pre-render the embed container -+ -.. Create a Liveboard embed within this `div`. -.. Before calling the Liveboard GUID, call `prerenderGeneric` to start the load process for the primary embed and transfer the bulk of the information needed by ThoughtSpot to render content to the client browser. -.. Pass an empty array into `useEffect`. +OR -+ -[source,TypeScript] +[source,JavaScript] ---- -useEffect(() => { - if (!ref.current) { - return; - } - lb.current = new LiveboardEmbed(ref.current, { - frameParams: { - height: "1200px" - } - }); - lb.current.prerenderGeneric(); -}, []); +// JavaScript +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; + +const embed = new LiveboardEmbed({ + preRenderId: 'pre-render-without-liveboard-id', + liveboardId: 'e40c0727-01e6-49db-bb2f-5aa19661477b', +}); + +embed.render(); ---- -. Navigate to Liveboard -+ -Update the render container when the user is ready to view the Liveboard. For this, use the previously defined context variable that sets the `liveboardId`, and leverage `useEffect` to register the changes to this ID. When the Liveboard ID is updated, render the new Liveboard by using the `navigateToLiveboard` function: -+ -[source,TypeScript] +This approach is more efficient than the previous one, but it does not load the Liveboard data and metadata until the end user actually navigates to the analytics page. So users might see a loading state for a few seconds before the Liveboard is loaded. + + +=== Pre-render on demand + +If you do not want your host app to fetch any ThoughtSpot resources during its initial load, this approach is ideal. + +In this mode, nothing is fetched until you actually render the embed. On the first render, all required assets and data are loaded. The iframe is then kept alive in the browser, so subsequent renders with the same `preRenderId` are instant because the existing iframe is reused. + +- Loads nothing up front; the embed is created only when the end user navigates to it. +- First visit loads normally; subsequent visits with the same `preRenderId` reuse the iframe and appear instantly. +- Most resource‑efficient; loads only if needed and avoids repeated work by reusing the iframe. +- Performance benefit is realized only when the user navigates back to the analytics page; the first visit behaves like a normal render. + +image::./images/pre-render/dig5_ondemand.png[] + +Since we are not 'preloading' any assets or data, this strategy does not require any pre-render component, simply pass a `preRenderId` prop to your normal component render. + +[source,JSX] ---- -useEffect(() => { - if (!liveboardId) { - return; - } - lb.current?.navigateToLiveboard(liveboardId); -}, [liveboardId]); + ---- -. Create context provider -+ -To manage context variables and render the shell we next need to create a provider component: - -+ -[Source,TypeScript] +[source,js] ---- -export const PrerenderdLiveboardProvider = ({ children }) => { - const [isVisible, setIsVisible] = useState(false); - const [liveboardId, setLiveboardId] = useState(); - const [coords, setCoords] = useState({ - left: 0, - top: 0, - height: 0, - width: 0 - }); - return ( - - {children} - - - ); -}; +// JavaScript +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; + +const embed = new LiveboardEmbed({ + preRenderId: 'pre-render-on-demand', + liveboardId: 'e40c0727-01e6-49db-bb2f-5aa19661477b', +}); + +embed.render(); ---- -. Add this code to your application -+ -In this example, the primary content is in a component named `LiveboardBrowser`. It includes a list of different liveboards that a user can choose from, and a space on the page to render the Liveboard. The IDs are hard-coded in this example. However, you can populate this via a REST call. +The value of `preRenderId` can be any string, but it must match the `preRenderId` you use when rendering the actual embed later. + +=== Normal Render + +- Default behavior. Loads the embed only when the component is rendered. +- On every visit, the iframe is recreated and the embed loads from scratch. +- Efficient if the embed is rarely used, but slow for the end user every time. + +image::./images/pre-render/dig2.png[] -+ -[source,TypeScript] +[source,JSX] ---- -init({ -thoughtSpotHost: "https://my.thoughtspot.cloud/", -authType: AuthType.None, // AuthType.Passthrough -}) - -function App() { - return ( -
- - - -
- ); -} + ---- -. Render a Liveboard -+ -.. Set our context variables -.. Specify the GUID of the Liveboard -.. Set coordinates for the element the shell will overlay -.. Set visibility to `true`. +[source,JavaScript] +---- +// JavaScript +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; + +const embed = new LiveboardEmbed({ + liveboardId: 'some-liveboard-id', +}); -+ -[source,TypeScript] +embed.render(); ---- -function toggleLiveboardSelect(e){ - setLiveboardId(e.target.value); - const coords = ref.current.getBoundingClientRect(); - const offset = getOffset(ref.current); - setCoords({ - height: coords.height, - width: coords.width, - top: offset.top, - left: offset.left - }); - setIsVisible(true); -} + +=== Prefetch assets + +- Loads a few common JS/CSS assets in parallel with your app. +- No Liveboard data or API calls are made. +- Minimal benefit. As modern browsers already cache static assets efficiently, using prefetch may not provide a significant performance gain. +- Wastes bandwidth if the end user never opens the embed. + +image::./images/pre-render/dig6_prefetch.png[] + + +[source,JavaScript] ---- +import { + prefetch, + PrefetchFeatures +} from '@thoughtspot/visual-embed-sdk'; + +prefetch("https://:", [ + PrefetchFeatures.LiveboardEmbed, + PrefetchFeatures.VizEmbed +]); +---- + +== Strategy Comparison Table -//// -== Turn on CDN +[cols="1,1,1,1,1,1,2",options="header"] +|===== +| Strategy | Loads in Parallel | Loads Data If Not Used | Loads Assets If Not Used | Reuses Iframe | Perceived Load Speed | Notes +| Normal Render | ❌ | ✅ No | ✅ No | ❌ | ❌ Slowest | No reuse; re-renders every time +| Prefetch | ✅ (few assets) | ✅ No | ⚠️ Yes (small assets) | ❌ | ⚠️ Slight improvement | Browser cache often makes it redundant +| Prerender + ID | ✅ | ❌ Yes | ❌ Yes | ✅ | ✅✅✅ Fastest | Best UX, worst resource efficiency +| Prerender w/o ID | ✅ | ✅ No | ⚠️ Yes (partial assets) | ✅ | ⚠️ Moderate | Trade-off between prep and efficiency +| On Demand | ❌ | ✅ No | ✅ No | ✅ | ✅ (on revisit), ❌ (first visit) | Best balance of performance and efficiency +|===== -Using a Content Delivery Network (CDN) reduces the time to pre-render static or dynamic ThoughtSpot assets by caching resources closer to the end user. When your application users navigate to ThoughtSpot very quickly after the embedding application loads, they need not wait for assets to finish pre-rendering. +=== Advanced Troubleshooting -The following figure illustrates the benefits of using CDN: +* If the pre-rendered component does not appear, check that the container is visible and the coordinates are set. +* The iframes are saved as a child components to the body and not in the given target element. -image::./images/cdn.png[CDN] +== Additional Resources -//// +* link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[Pre-rendering examples on GitHub, window=_blank] +* link:https://codesandbox.io/p/sandbox/github/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[CodeSandbox: Pre-rendering, window=_blank] diff --git a/modules/ROOT/pages/publishing-overview.adoc b/modules/ROOT/pages/publishing-overview.adoc index dabe14ab6..bf82dd224 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-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index 472554c25..3fe82006f 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -281,6 +281,7 @@ Note the recommendation of Java SDK: [options='header'] |==== |ThoughtSpot release version|Supported SDK version +a|ThoughtSpot Cloud: 10.14.0.cl | v2.19.0 or later a|ThoughtSpot Cloud: 10.13.0.cl | v2.18.0 or later a|ThoughtSpot Cloud: 10.12.0.cl | v2.17.0 or later a|ThoughtSpot Cloud: 10.11.0.cl | v2.16.0 or later diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index 345f4ffd3..dbd192eab 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -203,6 +203,7 @@ Note the version recommendations for your ThoughtSpot instances: [options='header'] |==== |ThoughtSpot release version|Recommended SDK version +a|ThoughtSpot Cloud: 10.14.0.cl | v2.19.0 or later a|ThoughtSpot Cloud: 10.13.0.cl | v2.18.0 or later a|ThoughtSpot Cloud: 10.12.0.cl | v2.17.0 or later a|ThoughtSpot Cloud: 10.11.0.cl | v2.16.0 or later diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 60cc36b23..f610cb71a 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,7 +8,87 @@ 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:: + +* 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. +* The `sensitive` parameter is renamed as `is_sensitive`. +//* You can define the data type for variables using the `data_type`property. +//* You can now create formula variables. To create a formula variable, use define the variable type as `FORMULA_VARIABLE` variable type in your API request . + + +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 +147,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..25e2ae71e 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. +* If a Model has a column alias, do not use the alias in runtime filters. Instead, use the underlying base column name. ==== === Runtime filter properties @@ -749,5 +750,3 @@ https://{ThoughtSpot-Host}/?col1=State&op1=EQ&val1=California&col2=product&op2=B * If the Model was created from an Answer (it is an aggregated Model), runtime filters will only work if the Answer was formed using a single Model. If the Answer from which the Model was created includes raw tables or joins multiple Models, you won't be able to use runtime filters on it. This is because of the join path ambiguity that could result. //// - - diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 08b47f4eb..2ea1a9a03 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -16,7 +16,7 @@ Runtime parameters can be applied using one of the following options: * Via Visual Embed SDK + Use the `runtimeParameters` property in the Visual Embed SDK for embedded objects. + The SDK also provides host events to update Parameters. -* Via RETS APIs + +* Via REST APIs + Use REST API requests to apply runtime overrides on Liveboard, Answer, or visualization data. * Via URL query parameters + Pass Parameter name and values as query parameters in the URL. @@ -97,50 +97,89 @@ Note the following behavior in Spotter embedding: * Users can see the Parameter value in formulas in edit mode, but only the value set for them will be visible. * Parameter values cannot be changed during a conversation session and may result in unintended effects. * 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. +* In Spotter embed, updating Parameters via host and embed events may not work as desired. -=== 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: +=== Adjust Parameter values using a host event +After loading the embedded object, Parameters can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateparameters[HostEvent.UpdateParameters] event. + +Developers can also set the Parameter chip visibility using the `isVisibleToUser` attribute in the `HostEvent.UpdateParameters` event payload. [source,JavaScript] ---- liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: "Date List Param", - value: 1656914873 + value: 1656914873, + isVisibleToUser: false }, { name: "Integer Range Param", - value: 10 + value: 10, + isVisibleToUser: false } ]) ---- -[NOTE] +[IMPORTANT] ==== -In Spotter embed, updating Parameters via host and embed events may not work. +Although the SDK allows setting `isVisibleToUser` for multiple Parameters in a single `HostEvent.UpdateParameters` request, we do not recommend passing different values of `isVisibleToUser` in a single `HostEvent.UpdateParameters` request. If you need to set different `isVisibleToUser` values for different Parameters, make separate `HostEvent.UpdateParameters` requests for each distinct override. ==== === 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. - -==== 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: -* 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) +Parameter values can be set or overridden using the following methods: -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. +* The `runtimeParameters` property in ThoughtSpot's Visual Embed SDK. + +Hides Parameter chips by default, but the Parameter values are applied to visualizations. +* The `HostEvent.UpdateParameters` event in the Visual Embed SDK. + +Allows overriding Parameter values and setting `isVisibleToUser` to show or hide the chip. By default, `isVisibleToUser` is set to `false`, so the chip is hidden, but the Parameter value is applied to visualizations. +* URL Parameter override (without SDK) + +Hides Parameter chips by default, but the value is applied to visualizations. -==== 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. +The following table describes parameter chip behavior in the embedded view: -[width="100%" cols="5,5,8"] +[width="100%" cols="5,6,8,8"] [options='header'] |===== -|Parameter chip|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` -|Hidden|Yes| Possible -|Shown| No| Possible +|Parameter chip state|Initialization method| Update via `HostEvent.UpdateParameters`? | Can change chip visibility? +|Visible a| No overrides applied | Possible a|Yes. By default, the chip will be hidden after an update via `HostEvent.UpdateParameters`. +To retain chip visibility after an override, you must explicitly set `isVisibleToUser` to `true` in your `HostEvent.UpdateParameters` request. +|Hidden a| Overrides applied via `runtimeParameters` in the Visual Embed SDK | Possible | No +|Hidden | Overrides applied via URL parameters| Possible| No |===== +==== Hide Parameter chips +To hide the parameter chip, initialize a Parameter override before loading the ThoughtSpot page using one of the following methods: + +* The `runtimeParameters` object in the Visual Embed SDK +* By applying a Parameter override directly in the URL + +You can also set the `isVisibleToUser` attribute to `false` in the `HostEvent.UpdateParameters` event payload to hide the chip after the Parameter update. + +[source,JavaScript] +---- +liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ + name: "Integer Range Param", + value: 10, + isVisibleToUser: false +}]) +---- + +==== Show Parameter chips + +To show a Parameter chip, update the Parameter value using `HostEvent.UpdateParameters` after the page has loaded. + + +Note that if a Parameter chip was hidden during initialization via `runtimeParameters` in the Visual Embed SDK or via URL query parameters, or if it was hidden by setting `isVisibleToUser` to `false` in a previous `HostEvent.UpdateParameters` request, then it will remain permanently hidden for the lifetime of the embed. Once hidden, a parameter cannot be made visible again unless you create a new embed object. + +However, if a Parameter chip is visible after initialization, you can retain its state by setting `isVisibleToUser` to `true`: + +[source,JavaScript] +---- +liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ + name: "Integer Range Param", + value: 10, + isVisibleToUser: true +}]) +---- + == 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..946cb0a36 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -6,9 +6,28 @@ :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 + + +** 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. +** The `sensitive` parameter is renamed as `is_sensitive`. + +* 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 +38,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 +53,34 @@ 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. +//* `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. +|`is_sensitive` __Optional__ |__Boolean__. Indicates if the variable contains sensitive values such as passwords. +|`data_type` + +Available from 10.15.0.cl onwards a|__String__. Variable data type. + +Supported data types are: +//Required parameter for formula variables. + +* `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. [NOTE] -This feature is disabled by default. To enable this option, contact ThoughtSpot Support. +The API doesn't support setting data type for the `TABLE_MAPPING`, `CONNECTION_PROPERTY`, and `CONNECTION_PROPERTY_PER_PRINCIPAL` variable types. -|`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. +|===== +//// |`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 +97,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] @@ -65,24 +108,11 @@ curl -X POST \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ + --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" - } - ] + "name": "TableVar", + "is_sensitive": true, + "data_type": "VARCHAR" }' ---- @@ -93,35 +123,31 @@ If the API request is successful, the following response is returned: [source,JSON] ---- { - "id": "180a9cd3-8605-445b-8b70-aa0bcef5dfb0", - "name": "schema_var", + "id": "3242b54c-69bc-4ff0-97cf-f99a2216b616", + "name": "TableVar", "variable_type": "TABLE_MAPPING", - "sensitive": false, - "values": [ - { - "value": "primaryOrg", - "org_identifier": "Primary", - "principal_type": null, - "principal_identifier": null, - "priority": null - } - ] + "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 +160,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 +188,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": "TableVar" }' ---- @@ -182,40 +206,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 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 +255,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 +284,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 +310,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 +324,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 +373,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..e695ee250 --- /dev/null +++ b/modules/ROOT/pages/webhooks-lb-schedule.adoc @@ -0,0 +1,1023 @@ += 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. + +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 need the following privileges: +** `APPLICATION_ADMINISTRATION` (*Can Manage Application settings*) to create and view communication channels. +** `CAN_MANAGE_WEBHOOKS` (*Can manage webhooks*) 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. +* Ensure that your destination application has a callback URL to accept HTTP POST requests from ThoughtSpot. +* 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 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" + ] + } + ] +}' +---- + +===== Example response + +If the request is successful, the API returns the channel preference details. + +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..01061ea56 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,55 @@ 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 + + +Key characteristics of code-based custom actions: + +* Can be maintained within your codebase to facilitate migration across organizations and clusters. +* Can have controlled visibility in ThoughtSpot by evaluating conditions within your application logic. This approach enables you to dynamically display or hide custom actions based on specific criteria, ensuring that only relevant actions are presented to users in different contexts. +* Can be assigned to Liveboards. +* Can be conditionally displayed based on the presence of a specific column in a visualization. + +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 +The variable APIs include several enhancements to streamline variable creation and update workflows. +For information about the new enhancements and breaking changes, see xref:rest-apiv2-changelog.adoc#_variable_api_enhancements[REST API changelog] and xref:variables.adoc[Variables documentation]. + +=== Parameter chip visibility configuration [tag redBackground]#BREAKING CHANGE# + +The `HostEvent.UpdateParameters` event in the Visual Embed SDK now includes the `isVisibleToUser` attribute, which allows you to control the visibility of Parameter chips on embedded ThoughtSpot pages. + +Before this enhancement, the Parameter chip display behavior was inconsistent across embed types when the Parameter values were updated via `HostEvent.UpdateParameters` requests. With the new change, the `isVisibleToUser` attribute in `HostEvent.UpdateParameters` is set to `false` by default for all embed types. + +With the new enhancement, the embedded pages that previously kept the parameter chip visible after an override via `HostEvent.UpdateParameters` will now hide it unless the `isVisibleToUser` attribute is explicitly set to `true`. + +This behavior may introduce a breaking change if your current implementation relies on the previous default chip visibility behavior. To retain chip visibility, developers must update their embedding implementation to pass `isVisibleToUser: true` in their `HostEvent.UpdateParameters` requests. + +For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Runtime Parameter overrides]. + +=== Pre-rendering enhancements +Pre-rendering now provides enhanced flexibility and granular control over for rendering embedded ThoughtSpot components. For more information, see xref:prerender.adoc[Pre-rendering ThoughtSpot Embed components]. + +=== 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..072bfc65a 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -35,53 +35,10 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '10.13.0.cl', + label: '10.14.0.cl', link: ' ', subLabel: 'Cloud (Latest)', - }, - { - label: '10.12.0.cl', - link: '10.12.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-10-12-0-cl.vercel.app/docs/', - }, - { - label: '10.11.0.cl', - link: '10.11.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-10-11-0-cl.vercel.app/docs/', - }, - { - label: '10.10.0.sw', - link: '10.10.0.sw', - subLabel: 'Software (Latest)', - iframeUrl: 'https://visual-embed-sdk-10-10.vercel.app/docs/', - }, - { - label: '10.1.0.sw', - link: '10.1.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', - }, - //{ - // label: '10.10.0.cl', - // link: '10.10.0.cl', - // subLabel: 'Cloud', - // iframeUrl: 'https://developer-docs-10-10-0-cl.vercel.app/docs/', - //}, - //{ - // label: '10.9.0.cl', - // link: '10.9.0.cl', - // subLabel: 'Cloud', - // iframeUrl: 'https://developer-docs-10-9-0-cl.vercel.app/docs/', - //}, - //{ - // label: '10.8.0.cl', - // link: '10.8.0.cl', - // subLabel: 'Cloud', - // iframeUrl: 'https://developer-docs-10-8-0-cl.vercel.app/docs', - //}, - + } ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', diff --git a/static/doc-images/images/pre-render/asset-split.png b/static/doc-images/images/pre-render/asset-split.png new file mode 100644 index 000000000..348ae6227 Binary files /dev/null and b/static/doc-images/images/pre-render/asset-split.png differ diff --git a/static/doc-images/images/pre-render/dig1.1.png b/static/doc-images/images/pre-render/dig1.1.png new file mode 100644 index 000000000..03ef0efb1 Binary files /dev/null and b/static/doc-images/images/pre-render/dig1.1.png differ diff --git a/static/doc-images/images/pre-render/dig1.2.png b/static/doc-images/images/pre-render/dig1.2.png new file mode 100644 index 000000000..35f533db5 Binary files /dev/null and b/static/doc-images/images/pre-render/dig1.2.png differ diff --git a/static/doc-images/images/pre-render/dig1.png b/static/doc-images/images/pre-render/dig1.png new file mode 100644 index 000000000..5ecd2371b Binary files /dev/null and b/static/doc-images/images/pre-render/dig1.png differ diff --git a/static/doc-images/images/pre-render/dig2.png b/static/doc-images/images/pre-render/dig2.png new file mode 100644 index 000000000..cbc60a6f9 Binary files /dev/null and b/static/doc-images/images/pre-render/dig2.png differ diff --git a/static/doc-images/images/pre-render/dig3_pre_with_livid.png b/static/doc-images/images/pre-render/dig3_pre_with_livid.png new file mode 100644 index 000000000..604ec5769 Binary files /dev/null and b/static/doc-images/images/pre-render/dig3_pre_with_livid.png differ diff --git a/static/doc-images/images/pre-render/dig4_wo_livid.png b/static/doc-images/images/pre-render/dig4_wo_livid.png new file mode 100644 index 000000000..0a5333dd8 Binary files /dev/null and b/static/doc-images/images/pre-render/dig4_wo_livid.png differ diff --git a/static/doc-images/images/pre-render/dig5_ondemand.png b/static/doc-images/images/pre-render/dig5_ondemand.png new file mode 100644 index 000000000..69eb235db Binary files /dev/null and b/static/doc-images/images/pre-render/dig5_ondemand.png differ diff --git a/static/doc-images/images/pre-render/dig6_prefetch.png b/static/doc-images/images/pre-render/dig6_prefetch.png new file mode 100644 index 000000000..16d4f6dd9 Binary files /dev/null and b/static/doc-images/images/pre-render/dig6_prefetch.png differ diff --git a/static/doc-images/images/pre-render/init-flow.png b/static/doc-images/images/pre-render/init-flow.png new file mode 100644 index 000000000..2c1e63550 Binary files /dev/null and b/static/doc-images/images/pre-render/init-flow.png differ diff --git a/static/doc-images/images/pre-render/pre-rendering-basic.png b/static/doc-images/images/pre-render/pre-rendering-basic.png new file mode 100644 index 000000000..6b149b431 Binary files /dev/null and b/static/doc-images/images/pre-render/pre-rendering-basic.png differ diff --git a/static/doc-images/images/pre-render/web-app.png b/static/doc-images/images/pre-render/web-app.png new file mode 100644 index 000000000..b3403bdaf Binary files /dev/null and b/static/doc-images/images/pre-render/web-app.png differ