From 6c7c6dd40ca4e0c5cb7e25d7d55c963f40f4ccf1 Mon Sep 17 00:00:00 2001 From: Ruchi Anand Date: Wed, 8 Oct 2025 10:13:22 +0530 Subject: [PATCH 01/29] updated theme builder url --- modules/ROOT/pages/theme-builder.adoc | 4 ++-- modules/ROOT/pages/whats-new.adoc | 4 ++-- src/components/DevDocTemplate/playGround/ThemeBuilder.tsx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/theme-builder.adoc b/modules/ROOT/pages/theme-builder.adoc index 3572283ec..bc66a7306 100644 --- a/modules/ROOT/pages/theme-builder.adoc +++ b/modules/ROOT/pages/theme-builder.adoc @@ -6,11 +6,11 @@ :page-pageid: theme-builder-doc :page-description: Understanding how to use the theme builder -Theme Builder[beta betaBackground]^Beta^ provides a graphical interface to explore the CSS customization options that are currently available for various ThoughtSpot components. You can try out these style customization options and get a preview of the desired look and feel before applying these changes to the ThoughtSpot components in your application environment. +Theme Builder provides a graphical interface to explore the CSS customization options that are currently available for various ThoughtSpot components. You can try out these style customization options and get a preview of the desired look and feel before applying these changes to the ThoughtSpot components in your application environment. In the current version, Theme Builder supports style customization options for embed components such as Liveboard, visualization, Search data page, and full ThoughtSpot app experience. The Theme Builder playground also provides an option to download and upload CSS variables with custom values in JSON format. -To access Theme Builder, click *Live Playgrounds* > *Theme Builder* [beta betaBackground]^Beta^ on this documentation site, or go to link:https://developers.thoughtspot.com/docs/theme-builder[https://developers.thoughtspot.com/docs/theme-builder, window=_blank]. +To access Theme Builder, click *Live Playgrounds* > *Theme Builder* on this documentation site, or go to link:https://developers.thoughtspot.com/docs/theme-builder[https://developers.thoughtspot.com/docs/theme-builder, window=_blank]. == Try out styles and load changes diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 36e4fb5d5..68863ca94 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -333,10 +333,10 @@ This release also introduces several enhancements to Spotter embed: For more information, see xref:embed-spotter.adoc[Embed Spotter]. ==== -.Theme builder for ThoughtSpot interface customization [beta betaBackground]^Beta^ +.Theme builder for ThoughtSpot interface customization [%collapsible] ==== -ThoughtSpot now offers link:https://developers.thoughtspot.com/docs/theme-builder[Theme Builder, window=_blank] [beta betaBackground]^Beta^, a graphical representation of CSS controls and themes to assist developers with the CSS customization framework. Theme Builder allows you to explore and preview the CSS customization options available with the Visual Embed SDK to customize the look and feel of the ThoughtSpot application interface. +ThoughtSpot now offers link:https://developers.thoughtspot.com/docs/theme-builder[Theme Builder, window=_blank], a graphical representation of CSS controls and themes to assist developers with the CSS customization framework. Theme Builder allows you to explore and preview the CSS customization options available with the Visual Embed SDK to customize the look and feel of the ThoughtSpot application interface. Developers embedding ThoughtSpot can preview the customization options in Theme Builder for various embed components, including Liveboard, Visualizations, Search page, and the full application experience. Additionally, you can view and download the default CSS variables in JSON format and upload a JSON file containing custom values for these CSS variables. diff --git a/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx b/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx index 0adf04417..7fa3847f8 100644 --- a/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx +++ b/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx @@ -2,7 +2,7 @@ import * as React from 'react'; import BackButton from '../../BackButton'; export const ThemeBuilder: React.FC = (props) => { - const playgroundUrl = 'https://thoughtspot-theme-builder-five.vercel.app/'; + const playgroundUrl = 'https://theme-builder-embed-prod.vercel.app/'; return (
From 4a799bb3daa51cd37aa79d2693c6137b860dc42e Mon Sep 17 00:00:00 2001 From: Ruchi Anand Date: Wed, 8 Oct 2025 10:32:14 +0530 Subject: [PATCH 02/29] reverting beta changes --- modules/ROOT/pages/whats-new.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 68863ca94..36e4fb5d5 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -333,10 +333,10 @@ This release also introduces several enhancements to Spotter embed: For more information, see xref:embed-spotter.adoc[Embed Spotter]. ==== -.Theme builder for ThoughtSpot interface customization +.Theme builder for ThoughtSpot interface customization [beta betaBackground]^Beta^ [%collapsible] ==== -ThoughtSpot now offers link:https://developers.thoughtspot.com/docs/theme-builder[Theme Builder, window=_blank], a graphical representation of CSS controls and themes to assist developers with the CSS customization framework. Theme Builder allows you to explore and preview the CSS customization options available with the Visual Embed SDK to customize the look and feel of the ThoughtSpot application interface. +ThoughtSpot now offers link:https://developers.thoughtspot.com/docs/theme-builder[Theme Builder, window=_blank] [beta betaBackground]^Beta^, a graphical representation of CSS controls and themes to assist developers with the CSS customization framework. Theme Builder allows you to explore and preview the CSS customization options available with the Visual Embed SDK to customize the look and feel of the ThoughtSpot application interface. Developers embedding ThoughtSpot can preview the customization options in Theme Builder for various embed components, including Liveboard, Visualizations, Search page, and the full application experience. Additionally, you can view and download the default CSS variables in JSON format and upload a JSON file containing custom values for these CSS variables. From ecfeb1bd1e6903527527c92c95347e1a07d2f267 Mon Sep 17 00:00:00 2001 From: Ruchi Anand Date: Wed, 8 Oct 2025 10:32:55 +0530 Subject: [PATCH 03/29] reverting beta changes --- modules/ROOT/pages/theme-builder.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/theme-builder.adoc b/modules/ROOT/pages/theme-builder.adoc index bc66a7306..3572283ec 100644 --- a/modules/ROOT/pages/theme-builder.adoc +++ b/modules/ROOT/pages/theme-builder.adoc @@ -6,11 +6,11 @@ :page-pageid: theme-builder-doc :page-description: Understanding how to use the theme builder -Theme Builder provides a graphical interface to explore the CSS customization options that are currently available for various ThoughtSpot components. You can try out these style customization options and get a preview of the desired look and feel before applying these changes to the ThoughtSpot components in your application environment. +Theme Builder[beta betaBackground]^Beta^ provides a graphical interface to explore the CSS customization options that are currently available for various ThoughtSpot components. You can try out these style customization options and get a preview of the desired look and feel before applying these changes to the ThoughtSpot components in your application environment. In the current version, Theme Builder supports style customization options for embed components such as Liveboard, visualization, Search data page, and full ThoughtSpot app experience. The Theme Builder playground also provides an option to download and upload CSS variables with custom values in JSON format. -To access Theme Builder, click *Live Playgrounds* > *Theme Builder* on this documentation site, or go to link:https://developers.thoughtspot.com/docs/theme-builder[https://developers.thoughtspot.com/docs/theme-builder, window=_blank]. +To access Theme Builder, click *Live Playgrounds* > *Theme Builder* [beta betaBackground]^Beta^ on this documentation site, or go to link:https://developers.thoughtspot.com/docs/theme-builder[https://developers.thoughtspot.com/docs/theme-builder, window=_blank]. == Try out styles and load changes From fa39fad742cee50b2a3b8e48590f429fe38afaef Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 8 Oct 2025 23:27:57 +0530 Subject: [PATCH 04/29] mcp abbr fix --- modules/ROOT/pages/mcp-integration.adoc | 2 +- modules/ROOT/pages/spotter-apis.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index af40cd213..4f5ebcb00 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -6,7 +6,7 @@ :page-pageid: mcp-integration :page-description: Learn how to use the ThoughtSpot Model Context Protocol (MCP) server to interact with ThoughtSpot data via MCP tools and AI APIs and get relevant questions and answers for a given query and create Liveboards at runtime. -ThoughtSpot’s Agentic Multi-Client Protocol (MCP) Server enables integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and 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. +ThoughtSpot’s Agentic Model Context Protocol (MCP) Server enables integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and 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 MCP tools of the Agentic MCP Server support the following functions: diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 622bc2a10..6eb6daad5 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -68,7 +68,7 @@ The following AI API endpoints allow you to initiate a conversation session with __This is a legacy API endpoint and will be deprecated in an upcoming release version__. === Create a conversation session with Spotter agent -The `/api/rest/2.0/ai/agent/conversation/create` API endpoint allows you to initiate a new conversation session with ThoughtSpot's AI Agent. Developers and system integrators embedding Spotter into agentic workflows, custom applications, or internal MCP (Managed Content Platform) servers, can use this API endpoint to create a conversation session from different data contexts such as Answers, Liveboards, or Models. +The `/api/rest/2.0/ai/agent/conversation/create` API endpoint allows you to initiate a new conversation session with ThoughtSpot's AI Agent. Developers and system integrators embedding Spotter into agentic workflows, custom applications, or internal Model Context Protocol (MCP) servers, can use this API endpoint to create a conversation session from different data contexts such as Answers, Liveboards, or Models. [NOTE] ==== From 131dc87760e2d42ab1200d504162ed85d6398fa2 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Sat, 18 Oct 2025 11:04:39 +0530 Subject: [PATCH 05/29] whats new for CBCA --- modules/ROOT/pages/whats-new.adoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 36e4fb5d5..c7fb5dec7 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,17 @@ 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 customization of actions for Liveboards, Visualizations, Answers, and Spotter. With this functionality, developers can add custom actions that show up as new menu options in one of the following UI elements: + +* the primary menu bar +* the **More** options menu image:./images/icon-more-10px.png[the more options menu] +* the contextual menu that appears when a user right-clicks on an Answer or visualization + + +Code based custom actions are flexible across Orgs and groups as well. + == Version 10.13.0.cl === Spotter AI APIs From 028fe2336b63b87ef4bbfafeed14acf231d4622f Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 22 Oct 2025 11:22:21 +0530 Subject: [PATCH 06/29] lb report --- modules/ROOT/pages/data-report-v2-api.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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*. ==== From 143f0766bab0d09c3660ba4ee580185655d1655f Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 23 Oct 2025 11:32:31 +0530 Subject: [PATCH 07/29] cbca change log --- modules/ROOT/pages/api-changelog.adoc | 12 ++++++++++++ modules/ROOT/pages/whats-new.adoc | 2 +- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0598d166e..d8227eac2 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,18 @@ 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|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. + + + == Version 1.42.0, October 2025 [width="100%" cols="1,4"] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index c7fb5dec7..39777e90e 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -11,7 +11,7 @@ This page lists new features, enhancements, and deprecated functionality in Thou == 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 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: +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] From 7324c235947eea97d50ee74608690d7be97827fc Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 23 Oct 2025 16:43:14 +0530 Subject: [PATCH 08/29] 10-14-0-docs --- modules/ROOT/pages/api-changelog.adoc | 8 + modules/ROOT/pages/common/nav.adoc | 2 + modules/ROOT/pages/mcp-integration.adoc | 345 +++++++-- modules/ROOT/pages/publishing-overview.adoc | 5 +- modules/ROOT/pages/rest-apiv2-changelog.adoc | 89 ++- modules/ROOT/pages/spotter-apis.adoc | 93 ++- modules/ROOT/pages/variables.adoc | 269 ++++--- modules/ROOT/pages/webhooks-kpi-alerts.adoc | 309 ++++++++ modules/ROOT/pages/webhooks-lb-schedule.adoc | 737 +++++++++++++++++++ modules/ROOT/pages/webhooks.adoc | 312 +------- modules/ROOT/pages/whats-new.adoc | 19 + 11 files changed, 1678 insertions(+), 510 deletions(-) create mode 100644 modules/ROOT/pages/webhooks-kpi-alerts.adoc create mode 100644 modules/ROOT/pages/webhooks-lb-schedule.adoc diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0598d166e..ba42a9fec 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,14 @@ 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]. +== Version 1.43.0, October 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*Code based custom actions* + +|==== + == Version 1.42.0, October 2025 [width="100%" cols="1,4"] diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 048de7dda..f583de45d 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -208,6 +208,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/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 4f5ebcb00..860de23b5 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -6,68 +6,82 @@ :page-pageid: mcp-integration :page-description: Learn how to use the ThoughtSpot Model Context Protocol (MCP) server to interact with ThoughtSpot data via MCP tools and AI APIs and get relevant questions and answers for a given query and create Liveboards at runtime. -ThoughtSpot’s Agentic Model Context Protocol (MCP) Server enables integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and 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. +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 MCP tools of the Agentic MCP Server support the following functions: +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: -* Ask natural language questions and get data in a structured format from ThoughtSpot -* Retrieve relevant analytical questions based on user queries -* Create a Liveboard with the answers generated from the queries -* Get data source recommendations based on a user's query and intent +* Enterprise Edition of ThoughtSpot Analytics +* ThoughtSpot Embedded subscription + +To learn more about the MCP Server subscription options and to get started, please contact your ThoughtSpot Sales representative. == Integration overview The Agentic MCP Server integration requires the following core components and authentication framework: MCP Server:: -The MCP Server provides a tools wrapper with a discoverable interface for agentic analytics. It exposes a set of tools to external agents to interact with ThoughtSpot's resources, data, and analytical capabilities. The MCP Server includes an orchestration layer that determines which tools to invoke based on the incoming queries and user intent. The MCP Server can be hosted by ThoughtSpot or by customers in their own environment. +The MCP Server exposes a set of tools that can be invoked by an LLM or external AI. ThoughtSpot's MCP Server acts as a bridge between the LLM/agent and ThoughtSpot application backend. -MCP tools, resources, and AI APIs:: -MCP tools are the actions that the MCP Server exposes to the agent for interaction with ThoughtSpot. Currently, the MCP Server supports the following tools: +MCP tools and resources:: +MCP tools are the actions that the MCP Server exposes to the agent for interaction with ThoughtSpot. + +* Ask natural language questions and get data in a structured format from ThoughtSpot +* Retrieve relevant analytical questions based on user queries +* Create a Liveboard with the answers generated from the queries +//* Get data source recommendations based on a user's query and intent + ++ +Currently, the MCP Server supports the following tools: * `ping` to test connection to ThoughtSpot * `getRelevantQuestions` to get relevant analytical questions + -The `getRelevantQuestions` tool calls xref:spotter-apis.adoc#_get_relevant_questions[/api/rest/2.0/ai/relevant-questions/] API and gets relevant data questions for a given data context by breaking down a user's query. +The `getRelevantQuestions` tool to fetch relevant data questions for a given data context by breaking down a user's query. * `getAnswer` to execute the queries and fetch data + -The `getAnswer` tool calls xref:spotter-apis.adoc#_send_a_question_and_generate_streaming_responses[/api/rest/2.0/ai/agent/converse/sse] API and generates answers and insights for a given data context. +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 user's query. + +//// * `getDataSourceSuggestions` to get data source suggestions + Based on the type of data that users want to fetch, `getDataSourceSuggestions` gets a list of data source recommendations. Currently, `getDataSourceSuggestions` is not exposed as an MCP tool and is available as an MCP `resource`. To get data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources. +//// -MCP host/client:: -The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface, orchestrates interaction with ThoughtSpot MCP Server, and enables agentic workflows. +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 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. +//// Configuration settings to enable the integration:: Integration requires configuration, typically via a config file, to specify server addresses, credentials, and other connection details. +//// Authentication and security settings:: + * Access to ThoughtSpot instance: + -For MCP Server connection, users require access to a ThoughtSpot instance. ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in the users. + -To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create Liveboard, users +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 the users. + +* SAML redirect settings: + +For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. + +* To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create Liveboard, users require data download privilege. * CSP and CORS settings: + To secure communication between the MCP client and the ThoughtSpot instance, administrators must add the MCP Server URL to CSP (Content Security Policy) and CORS (Cross-Origin Resource Sharing) allowlists in ThoughtSpot. -* SAML redirect settings: + -For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. * Client connection configuration: + MCP Server integration also requires configuration on the client side, typically via a config file, to include the MCP Server addresses, credentials, and other details. + === How it works -When the MCP Server integration is enabled, your host app connects to ThoughtSpot and enables the following workflow: - -. User initiates a request. + -The user sends a query to get data from a specific ThoughtSpot data model or context. -. AI agent receives the request and discovers the MCP tools + -The agent discovers MCP tools available in its environment and processes the request to the MCP Server, specifying the data model or context and the user's query. -. MCP Server receives the request and executes actions via tools + -The MCP Server executes tools and triggers API requests to ThoughtSpot to break down the user's query into relevant questions, get information for the specified data context, or create an artifact. -. The MCP Server sends the response to the MCP host. -. The agent receives the response and constructs the output + -The agent receives the response from the MCP host, constructs the output, and presents it to the user. -. User receives the response + -The user can refine the analysis or choose a direction for further exploration. + -For example, after receiving relevant questions and answer, the user can send follow-up questions or send a Liveboard creation request. +The MCP Server integration with an agentic framework or LLM clients enables the following workflow: + +. 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 create an artifact in ThoughtSpot programmatically. +. The MCP server processes the request and returns the result. +. The agent receives the response, constructs the output, and presents it to the user. +. User receives the response. The user can refine the analysis with follow-up queries for further exploration or ask a new question. + +For example, after receiving relevant questions and answers, the user can send follow-up questions or initiate a Liveboard creation request. The following figure illustrates the sequence of workflows in a typical MCP Server integration setup: @@ -86,6 +100,13 @@ Before you begin, verify if your application setup has the following: * Your application users have at least view access to the data source objects to query data and get answers. * Row-level and column-level security rules are configured for data security and access control. +To enable secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: + +. On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. +. Add the MCP Server domain to CSP and CORS allowlists. +. If your setup uses SAML SSO logins, add the MCP Server domain to the SAML redirect domain allowlist. + +//// === Configure security settings on ThoughtSpot To allow the secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: @@ -93,12 +114,231 @@ To allow the secure communication between the MCP Server and your ThoughtSpot in . On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. . Add the MCP Server domain to CSP and CORS allowlists. . If your setup uses SAML SSO logins, add the MCP Server domain to the SAML redirect domain allowlist. +//// + +=== Connect your client to the MCP Server + +If using a client that supports remote MCPs natively such as Claude AI, use the following MCP server URL: +---- +https://agent.thoughtspot.app/mcp +---- + +For OpenAI ChatGPT Deep Research, use the following URL: +---- +https://agent.thoughtspot.app/openai/mcp +---- + +For MCP clients such as Claude Desktop, Windsurf, Cursor, that do not support remote MCP Server, you must xref:mcp-integration.adoc#_connecting_other_mcp_clients_claude_desktop[add the MCP server configuration to your MCP client settings]. + +=== Call MCP tools via LLM APIs + +ThoughtSpot remote MCP Server acts as a wrapper over the ThoughtSpot APIs, making them available as tools for agent frameworks or LLMs such as Claude or OpenAI. It exposes specific tools to get relevant questions, answer, datasource suggestions, or create a Liveboard, which can be invoked by the LLMs in response to a user's query or prompt. + +To enable tool calling: + +* Register the ThoughtSpot MCP Server endpoint as a tool provider in your LLM or agent framework. +* Provide an authentication (OAuth or token-based) token. + +You can generate an authentication token for a specific user from ThoughtSpot via a `POST` call to the `/api/rest/2.0/auth/token/full` REST API endpoint. + +Logged-in users can view the authentication token for their current session by using the `/api/rest/2.0/auth/session/token` REST API endpoint or by opening the following URL in a new tab on the web browser: ++ +`https://{your-ts-instance}/api/rest/2.0/auth/session/token` + +For information about calling MCP tools using LLM APIs and methods, see these sections: + +* xref:mcp-integration.adoc#_claude_mcp_connector[Claude MCP connector] +* xref:mcp-integration.adoc#_openai_api_for_mcp_tool_calling[OpenAI API] +* xref:mcp-integration.adoc#_gemini_api[Gemini API and function calling] + +==== Claude MCP connector +Claude’s MCP connector feature enables you to connect to remote MCP Servers directly from the Messages API. + +To connect to the ThoughtSpot remote MCP Server, specify the following properties in the API request: + +* `mcp_servers` + +In the `mcp_servers` array, include these parameters: + +** `type` + +__String__. Type. Specify the type as `url`. +** `url` + +__String__. The URL of the remote MCP Server endpoint. Must start with `https://`. +** `name` + +__String__. A unique identifier/label for the MCP Server. It will be used in the MCP tool call blocks to identify the server and to disambiguate tools to the LLM. +** `authorization_token` + +__String__. OAuth authorization token (`TS_AUTH_TOKEN`) along with the ThoughtSpot application instance URL. In the following example, authorization token is prefixed, and the ThoughtSpot host URL is added with the `@` symbol. + +* `messages` + +In the `messages` array, specify a natural language question in `content` and the user role in `role`. + +* `model` + +LLM model to use for processing queries and interacting with tools. For example, claude-sonnet-4-20250514. + +[source,cURL] +---- +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "X-API-Key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: mcp-client-2025-04-04" \ + -d '{ + "model": "claude-sonnet-4-20250514", + "max_tokens": 1000, + "messages": [{ + "role": "user", + "content": "How do I increase my sales ?" + }], + "mcp_servers": [ + { + "type": "url", + "url": "https://agent.thoughtspot.app/bearer/mcp", + "name": "thoughtspot", + "authorization_token": "$TS_AUTH_TOKEN@my-thoughtspot-instance.thoughtspot.cloud" + } + ] + }' +---- + +//// +[source,TypeScript] +---- +import { Anthropic } from '@anthropic-ai/sdk'; + +const anthropic = new Anthropic(); + +const response = await anthropic.beta.messages.create({ + model: "claude-sonnet-4-5", + max_tokens: 1000, + messages: [ + { + role: "user", + content: "How do I increase my sales ?", + }, + ], + mcp_servers: [ + { + type: "url", + url: "https://agent.thoughtspot.app/bearer/mcp", + name: "thoughtspot", + authorization_token: "$TS_AUTH_TOKEN@my-thoughtspot-instance.thoughtspot.cloud", + }, + ], + betas: ["mcp-client-2025-04-04"], +}); +---- +//// + +The request uses Claude’s internal tool-calling mechanism to call the MCP endpoint with the provided token, discover the available tools, and retrieve data for the user's query. + +For more information, see the link:https://docs.claude.com/en/docs/agents-and-tools/mcp-connector[Claude MCP connector documentation, window=_blank]. + +==== OpenAI API for MCP tool calling +To enable tool calling and retrieve data from ThoughtSpot via OpenAI, you can use the Responses API endpoint. + +To connect to the ThoughtSpot remote MCP server, call the `https://api.openai.com/v1/responses` API endpoint and specify the following properties in the API request: + +* `tools` + +In the `tools` array, include these parameters: + +** `server_url` + +The URL of the ThoughtSpot MCP Server. Use the full path of the MCP server URL. +** `server_label` + +Label of the ThoughtSpot MCP Server +** `type` + +Type of tool. For example, MCP. +** `headers` + +Additional headers needed for authentication, for example, the authentication token and URL of the ThoughtSpot host. + +* `input` + +Include the natural language query string as `input`. +* `model` + +LLM model to use for processing queries and interaction with tools. For example, GPT-5 or GPT 4.1. -=== Add MCP Server to the MCP client's config +[source,cURL] +---- +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "tools": [ + { + "type": "mcp", + "server_label": "thoughtspot", + "server_url": "https://agent.thoughtspot.app/bearer/mcp", + "headers": { + "Authorization": "Bearer $TS_AUTH_TOKEN", + "x-ts-host": "my-thoughtspot-instance.thoughtspot.cloud" + } + } + ], + "input": "How can I increase my sales ?" +}' +---- + +If the API request is successful, the LLM discovers the available MCP tools from the MCP Server endpoint. Once the model has access to these tools, it determines the tool to call depending on the user's query and what's in the model's context. + +For more information, see link:https://platform.openai.com/docs/guides/tools-connectors-mcp[Open AI Connectors and MCP Server Documentation]. + +==== Gemini API -If your MCP client supports remote MCP Servers, add the MCP Server URL to the client's config file. +You can use the standard function calling mechanism provided in Gemini Python/Typescript SDK. The Gemini SDK supports MCP natively, and can pass tool definitions and call tools. -MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote MCP Servers. In such a case, add the URL with arguments shown in this example: +In the following example, a session linked to the ThoughtSpot remote MCP Server is passed along with the authorization token and the ThoughtSpot host, so that the SDK can handle tool calling. + +[source,TypeScript] +---- +import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai'; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; + +// Create server parameters for stdio connection +const serverParams = new StreamableHTTPClientTransport(new URL("https://agent.thoughtspot.app/bearer/mcp"), { + requestInit: { + headers: { + "Authorization": "Bearer $TS_AUTH_TOKEN", + "x-ts-host": "my-thoughtspot-instance.thoughtspot.cloud" + }, + } +}); + +const client = new Client( + { + name: "example-client", + version: "1.0.0" + } +); + +// Configure the client +const ai = new GoogleGenAI({}); + +// Initialize the connection between client and server +await client.connect(serverParams); + +// Send request to the model with MCP tools +const response = await ai.models.generateContent({ + model: "gemini-2.5-flash", + contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`, + config: { + tools: [mcpToTool(client)], // uses the session, will automatically call the tool + // Uncomment if you **don't** want the sdk to automatically call the tool + // automaticFunctionCalling: { + // disable: true, + // }, + }, +}); +console.log(response.text) + +// Close the connection +await client.close(); +---- + +For additional information, refer to the following resources: + +* For more information about Gemini API MCP tool calling, see link:https://ai.google.dev/gemini-api/docs/function-calling?example=meeting#mcp[Function calling with the Gemini API documentation, window=_blank]. +* A link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-google-adk-trusted-auth[developer example with Google ADK and Python implementation] is also available in the link:https://github.com/thoughtspot/developer-examples[ThoughtSpot Developer Examples GitHub repository, window=_blank]. +* The ThoughtSpot MCP server can also be installed as a Gemini CLI extension. For more information, see link:https://github.com/google-gemini/gemini-cli[Gemini CLI, window=_blank]. + +=== For clients that do not support the remote MCP server + +For clients such as Claude Desktop, Windsurf, Cursor, which do not support remote MCP servers, add the following configuration to your MCP client settings: [source,JSON] ---- @@ -113,7 +353,6 @@ MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote M } } } - ---- After updating the config file: @@ -121,7 +360,8 @@ After updating the config file: . When prompted to connect your ThoughtSpot instance, add the URL of your application instance and complete authentication. . Restart your MCP client to load the new configuration. + -If the connection is successful, you'll see an option to connect to ThoughtSpot and choose the data context. + +If the connection is successful, you'll see an option to connect to ThoughtSpot and choose the data context. ++ For example, the Claude Desktop shows the *Add to ThoughtSpot* as shown in the following figure: + [.bordered] @@ -130,44 +370,23 @@ image::./images/claudeDesktop.png[Claude Desktop] . Verify if the MCP tools are available. + For example, on Claude Desktop, click the Search and tools icon to view the MCP tools. - + [.bordered] [.widthAuto] image::./images/mcp-tools-claude.png[Claude Desktop] -You can adjust tool access, resources, instructions to data models, object permissions, and user privileges as needed. To get insights, the user requires view access to the data source objects and data download privilege. - -=== Verify the query and response workflow - -* Select a data source to set the context of your query. + -For example, on Claude Desktop, click the `+` icon and select a data source. - -+ -[.bordered] -[.widthAuto] -image::./images/datasource-selection.png[Claude Desktop] - -* Ask an analytics question to trigger the query and response workflow. -* Verify if the AI agent on your MCP client gets relevant data questions from ThoughtSpot and generates an Answer. +. Select a data source to set the context of your query and verify the request and response flow. + [.bordered] [.widthAuto] image::./images/query-response-claude.png[Claude query response] -+ -[.bordered] -[.widthAuto] -image::./images/query-response-claude2.png[Claude query response 2] - -* Try sending a query to create a Liveboard and verify if a Liveboard is created on your ThoughtSpot instance. - +. Try sending a query to create a Liveboard and verify if a Liveboard is created on your ThoughtSpot instance. + [.bordered] [.widthAuto] image::./images/create-lb-claude.png[Liveboard creation] - == Configuration considerations and best practices * Users must have at least view access to the data source. Otherwise, it may lead to empty results. @@ -179,9 +398,9 @@ image::./images/create-lb-claude.png[Liveboard creation] * Check the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repo, window=_blank] for implementation instructions. * Check your MCP client's documentation for instructions on how to connect to MCP Servers. -* To understand ThoughtSpot agentic analytics capabilities and AI APIs, refer to the following documentation: +* In case of issues with connection or authentication, refer to the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^]. +* To understand ThoughtSpot's agentic analytics capabilities and AI APIs, refer to the following documentation: -** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation] -** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation] +** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation, window=_blank] +** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation, window=_blank] ** xref:spotter-apis.adoc[Spotter AI APIs] -* In case of issues with connection or authentication, refer to the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^]. \ No newline at end of file diff --git a/modules/ROOT/pages/publishing-overview.adoc b/modules/ROOT/pages/publishing-overview.adoc index dabe14ab6..973652808 100644 --- a/modules/ROOT/pages/publishing-overview.adoc +++ b/modules/ROOT/pages/publishing-overview.adoc @@ -14,7 +14,7 @@ Starting with the 10.10.0.cl release, ThoughtSpot provides a set of REST APIs fo [IMPORTANT] ==== -The publishing feature—including the REST APIs for variable creation and update, metadata parameterization, and publishing content across Orgs—is in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +The publishing feature, including the REST APIs for variable creation and update, metadata parameterization, and publishing content across Orgs, is in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== == When to use publishing feature @@ -69,6 +69,9 @@ This variable supports modifying connection properties per principal (user or us The `CONNECTION_PROPERTY_PER_PRINCIPLE` variable does not allow parameterizing core connection properties such as `accountName`, `host`, or `port`. These properties must be derived from the connection configuration and cannot be set per user or user group. + || + +`FORMULA_VARIABLE` a| `FORMULA_VARIABLE` refers can be used to create and manage formula variables. +| |===== The following figure illustrates variable substitution in Connections and Tables: diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 60cc36b23..dac50f494 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,7 +8,84 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. -== Version 10.14.0.cl, October 2025 +== Version 10.14.0.cl, November 2025 + +=== New API endpoints + +System:: +This release introduces the following endpoints for configuring communication channel preference. + +* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + +Sets a communication channel preference for all Orgs at the cluster level or at the indiviudal Org level. +* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + +Gets details of the communication channel preferences configured on ThoughtSpot. ++ +For more information, see xref:webhooks-lb-schedule.adoc#_configure_a_webhook_communication_channel_for_the_liveboard_schedule_event[Webhooks for Liveboard schedule events] + +Webhook:: +The following APIs are introduced for webhook crud operations: +* `POST /api/rest/2.0/webhooks/create` +Creates a webhook. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` +Updates the properties of a webhook +* `POST /api/rest/2.0/webhooks/search` +Gets a list of webhooks configured in ThoughtSpot or a specific Org in ThoughtSpot +* `POST /api/rest/2.0/webhooks/delete` +Deletes the webhook. ++ +For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. + +Column security rules:: + +* `POST /api/rest/2.0/security/column/rules/update` + +Updates column security rules for a given Table. + +* `POST /api/rest/2.0/security/column/rules/fetch` + +Gets details of column security rules for the tables specified in the API request. + +//// + +Spotter:: +POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse +//// +=== Variable API enhancements + +The following enhancements are introduced in variable API endpoints: + +Variable creation:: + +* You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in the API request to the `/api/rest/2.0/template/variables/create` API endpoint . +* The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `POST /api/rest/2.0/template/variables/update-values` API endpoint. + +Variables update:: +[tag redBackground]#BREAKING CHANGE# +* The `/api/rest/2.0/template/variables/update` 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` API endpoint. +* The resource path for updating multiple variable values has changed from `POST /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, the `POST /api/rest/2.0/template/variables/update-values` API endpoint. + +Variables search:: +* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter to allow users to filter API response by variable values. +* Filtering API response by `EDITABLE_METADATA_AND_VALUES` output format is no longer supported. + +For more information, see xref:variables.adoc[Define variables]. + +=== User API enhancements +The following APIs now support `variable_values` parameter. The `variable_values` property can be used for user-specific customization. + +* `POST /api/rest/2.0/users/create` +* `POST /api/rest/2.0/users/search` +* `POST /api/rest/2.0/users/activate` + +=== DBT API enhancements +The `/api/rest/2.0/dbt/generate-tml` endpoint supports `model_tables` attribute to allow listing Models and its Tables. + +//// + +=== Authentication API +Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. + +//// + +== Version 10.13.0.cl, October 2025 === New API endpoints @@ -67,16 +144,6 @@ The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and rep The following API endpoints are now available: -//// -Column security rules:: - -* `POST /api/rest/2.0/security/column/rules/update` + -Updates column security rules for a given Table. - -* `POST /api/rest/2.0/security/column/rules/fetch` + -Gets details of column security rules for the tables specified in the API request. -//// - Custom calendar:: * `POST /api/rest/2.0/calendars/create` + Creates a custom calendar. diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 6eb6daad5..7cab136a1 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -57,6 +57,14 @@ __Limited availability on ThoughtSpot Cloud instances from 10.13.0.cl onwards. P ==== //// +=== Locale settings for API requests + +When using the xref:spotter-apis.adoc#_generate_a_single_answer[Single Answer] and xref:spotter-apis.adoc#_send_a_question_to_generate_answer[Send message] APIs, the locale used for API requests depends on your application's locale settings: + +* If your application is set to "Use browser language," the API will not apply the default locale. In this case, you must explicitly include the desired locale code in the `Accept-Language` header of your API request. If you do not specify the locale, the API may not return responses in the expected language or format. +* If you have set a specific locale in your ThoughtSpot instance or user profile, the API will use this locale to generate responses, overriding the browser or OS locale + +To ensure consistent localization, set the `Accept-Language` header in your API requests when relying on browser language detection, or configure the locale explicitly in the user profile settings in ThoughtSpot. == Create a conversation session A conversation session acts as a container for maintaining continuity across user inputs, system responses, and agent-driven clarifications. Once created, users can send queries or ask follow-up questions to the conversation session to explore data and get further insights. @@ -82,26 +90,28 @@ To set the context for the conversation session, you must specify the metadata t [options='header'] |===== |Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. Specify the following values: +|`metadata_context` a| Defines the data context for the conversation. * `type` + -Metadata type. Valid values are: -** `answer` - To use an existing Spotter-generated Answer as the object -** `liveboard` - To use an existing Liveboard as data object -** `data_source` - To create a new conversation session using data objects such as Model. -+ +Metadata context type. The context type is mandatory. Select one of the following values: +** `data_source` - To set a data source context for the conversation session. + +If the context type is `data_source`, you must define the `data_source_context` in the request payload. +** `answer` - To use an existing Spotter-generated Answer as the object. + +If the context type is `answer`, you must define both `data_source_context` and `answer_context` in the request payload. +** `liveboard` - To use an existing Liveboard as context. + +If the context type is `liveboard`, you must define `data_source_context`, `liveboard_context`, and `answer_context` in the request payload. * `answer_context` + -If the metadata type is set as `answer`, specify the following attributes: +If the metadata type is set as `answer` or `liveboard`, specify the following attributes: ** `session_identifier`: __string__, Unique ID representing the answer session. ** `generation_number`: __Integer__. Specific generation/version number of the answer within a conversation session. + The session identifier and generation numbers are assigned to the Answers generated from the Spotter AI REST APIs. These properties serve as the ID of the AI-generated Answer within the ThoughtSpot system. * `liveboard_context` + -If the metadata type is set as `liveboard`, specify the GUID of the Liveboard and visualization. +If the metadata type is set as `liveboard`, specify the GUIDs of the Liveboard and visualization. * `data_source_context` + -If the metadata type is set as `data_source`, specify the GUID of the data source object. +Specify the GUID of the data source object. Required parameter for all types of metadata context. |`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: @@ -115,6 +125,8 @@ __Boolean__. Allows Spotter to use reasoning for deep analysis and precise respo ==== Example request +The following example shows the request payload for the `data_source` context type: + [source,cURL] ---- curl -X POST \ @@ -137,6 +149,63 @@ curl -X POST \ }' ---- +The following example shows the request payload for the `liveboard` context type: +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "liveboard", + "answer_context": { + "session_identifier": "c3a00fa7-fd01-4d58-8c84-0704df986d9d", + "generation_number": 2 + }, + "liveboard_context": { + "liveboard_identifier": "cffdc614-0214-42ba-9f57-cb6e8312fe5a", + "visualization_identifier": "da0ed3da-ce1f-4071-8876-74d551b05faf" + }, + "data_source_context": { + "guid": "54beb173-d755-42e0-8f73-4d4ec768114f" + } + }, + "conversation_settings": { + "enable_contextual_change_analysis": false, + "enable_natural_language_answer_generation": true, + "enable_reasoning": false + } +}' +---- + +The following example shows the request payload for the `answer` context type: + +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "answer", + "answer_context": { + "session_identifier": "f131ca07-47e9-4f56-9e21-454120912ae1", + "generation_number": 1 + }, + "data_source_context": { + "guid": "cd252e5c-b552-49a8-821d-3eadaa049cca" + } + }, + "conversation_settings": { + "enable_contextual_change_analysis": false, + "enable_natural_language_answer_generation": true, + "enable_reasoning": false + } +}' +---- + ==== API response If the API request is successful, the API returns the conversation ID. You can use this ID to send follow-up questions to the conversation session. @@ -146,7 +215,7 @@ If the API request is successful, the API returns the conversation ID. You can u {"conversation_id":"q9tZYf_6WnFC"} ---- -Note the conversation ID for further agentic interactions and API calls. +Note the conversation ID for subsequent agentic interactions and API calls. === Create a conversation session (legacy API endpoint) To create a conversation session, send a `POST` request body with the data source ID and search token string to the `/api/rest/2.0/ai/conversation/create` API endpoint. @@ -728,6 +797,7 @@ To send a question to an ongoing conversation session or ask follow-up questions curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/conversation/03f48527-b973-4efa-81fd-a8568a4f9e78/converse' \ -H 'Accept: application/json' \ + -H 'accept-language: en-US', \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ @@ -815,7 +885,6 @@ The API retrains the context of the initial question and returns a response: |=== //// - == Generate a single Answer To generate an Answer from a natural language search query, send a `POST` request to the `/api/rest/2.0/ai/answer/create` API endpoint. In the request body, include the query and the data source ID. @@ -836,6 +905,7 @@ To generate an Answer from a natural language search query, send a `POST` reques curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/answer/create' \ -H 'Accept: application/json' \ + -H 'accept-language: en-US', \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN} \ --data-raw '{ @@ -875,7 +945,6 @@ Note the session ID and generation number. To export the result generated from t }] ---- - [#process_results] == Process results generated from Spotter APIs To generate an Answer using the data returned from the Spotter APIs, use the following options: diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc index cefffeb5d..f7fa64e85 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -6,9 +6,27 @@ :page-pageid: variables :page-description: Use the variables REST API to create and update variables for publishing content across Orgs -Variables allow you to define dynamic placeholders for specific properties of metadata objects such as Connections and Tables. By using variables, you can dynamically assign different values to the object properties for each Org and yet use a single source with a consistent data structure across different Orgs. +Variables allow you to define dynamic placeholders for specific properties of metadata objects such as Connections and Tables. By using variables, you can dynamically assign different values to the object properties for each Org and yet use a single source with a consistent data structure across different Orgs. Before publishing an object to other Orgs, define variables for each Org and assign these variables to the metadata object properties. -Before publishing an object to other Orgs, define variables for each Org and assign these variables to the metadata object properties. + +[IMPORTANT] +==== +Note the following enhancements and breaking changes introduced in ThoughtSpot Cloud 10.14.l0.cl release: + +* Variable creation + +** You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in the API request to the `/api/rest/2.0/template/variables/create` API endpoint . +** The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `POST /api/rest/2.0/template/variables/update-values` API endpoint. + +* Variables update + +** The `/api/rest/2.0/template/variables/update` 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` API endpoint. +** The resource path for updating multiple variable values has changed from `POST /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, the `POST /api/rest/2.0/template/variables/update-values` API endpoint. + +* Variables search + + +** Filtering API response by `EDITABLE_METADATA_AND_VALUES` output format is no longer supported. + +ThoughtSpot recommends updating your application setup and workflows to avoid operational issues in your environment. +==== == Before you begin @@ -19,7 +37,7 @@ Before publishing an object to other Orgs, define variables for each Org and ass To create a variable, send a `POST` request to the +++/api/rest/2.0/template/variables/create +++ API endpoint, with the following parameters in the request body. === Request parameters -In your `POST` request body, you can include the following parameters: +In your `POST` request body, include the following parameters: [width="100%" cols="1,4"] [options='header'] @@ -34,12 +52,26 @@ To map Tables properties to variables. To define variables for connection properties. This variable allows editing connection properties such as `accountName`, `warehouse`, `user`, `password`, `role` and so on. * `CONNECTION_PROPERTY_PER_PRINCIPAL` + To define variables for connection properties per user or user group. This variable allows modifying connection properties such as `warehouse`, `role`, `user`, `password`. The `CONNECTION_PROPERTY_PER_PRINCIPLE` variable does not support modifying core connection properties such as `accountName`, `host`, or `port`. These properties must be derived from the connection configuration and cannot be set per user or user group. - -[NOTE] -This feature is disabled by default. To enable this option, contact ThoughtSpot Support. - +* `FORMULA_VARIABLE` + +Formula variables. |`name`| __String__. Name of the variable. For example, `schema_var`. Note that the name must be unique across all Orgs within the instance. |`sensitive` __Optional__ |__Boolean__. Indicates if the variable contains sensitive values such as passwords. +|`data_type`|__String__. Variable data type. Required parameter for formula variables. Supported data types are: + +* `VARCHAR` + +String. For example, "East", "Administrator", "Secure", "2025-10-23" +* `INT32` +32-bit integer data type. For example, 100,-42 +* `INT64` +32-bit integer data type. For example, 0, 2147483647 +* `DOUBLE` + +The Double data type refers to a floating point numeric type that is recommended for storing decimal values. For example, 3.14, -0.001, 100.0, 1.7E+308. In ThoughtSpot, DOUBLE is used for columns that require floating point arithmetic or need to store decimal numbers, such as latitude and longitude or financial amounts. +* `DATE` +Date format. For example, 2025-10-20. +* `DATE_TIME` +Date with time stamp. For example, 2025-10-20 14:30:00. +|===== +//// |`values` __Optional__ a|__Array of strings__. Define the variable attributes. Although it's optional, make sure that you set the value for an Org before publishing content to that Org. The `values` array includes the following attributes: @@ -56,6 +88,8 @@ Applicable if the variable type is set as `CONNECTION_PROPERTY_PER_PRINCIPAL`. S Applicable if the variable type is set as `CONNECTION_PROPERTY_PER_PRINCIPAL`. The priority assigned to this value. If there are two matching values, the one with a higher priority will be used. |===== +//// + === Example request [source,cURL] @@ -66,23 +100,10 @@ curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "type": "TABLE_MAPPING", - "name": "schema_var", - "sensitive": false, - "values": [ - { - "value": "primary", - "org_identifier": "primaryOrg" - }, - { - "value": "TargetOrg1", - "org_identifier": "MyOrg1" - }, - { - "value": "TargetOrg2", - "org_identifier": "MyOrg2" - } - ] + "type": "FORMULA_VARIABLE", + "name": "my_formula_variable", + "is_sensitive": false, + "data_type": "DATE" }' ---- @@ -93,35 +114,31 @@ If the API request is successful, the following response is returned: [source,JSON] ---- { - "id": "180a9cd3-8605-445b-8b70-aa0bcef5dfb0", - "name": "schema_var", - "variable_type": "TABLE_MAPPING", - "sensitive": false, - "values": [ - { - "value": "primaryOrg", - "org_identifier": "Primary", - "principal_type": null, - "principal_identifier": null, - "priority": null - } - ] + "id": "3242b54c-69bc-4ff0-97cf-f99a2216b616", + "name": "my_formula_variable", + "variable_type": "FORMULA_VARIABLE", + "sensitive": true, + "values": [] } ---- Note the variable ID. + == Update variable values -To update a variable, the following APIs are available: +To update a variable or properties of a variable, use the following REST APIs: -* `+++POST /api/rest/2.0/template/variables/update+++` +* `+++POST /api/rest/2.0/template/variables/{identifier}/update+++` + -Allows adding, removing, and replacing values for multiple variables in a single API call. +Allows updating the properties of a variable. -* `+++POST /api/rest/2.0/template/variables/{identifier}/update+++` +//* `+++POST /api/rest/2.0/template/variables/{identifier}/update+++` + +* +++POST /api/rest/2.0/template/variables/update-values+++ + -Allows adding, removing, and replacing values of a specific variable. +Allows adding, removing, and replacing values of one or several variables configured in ThoughtSpot. + === Update properties of a variable @@ -134,7 +151,12 @@ In your `POST` request body, you can include the following parameters: [width="100%" cols="1,4"] [options='header'] |===== -|Parameter|Description +|Parameter|Type|Description +|`identifier` |Path |__String__. Name or ID of the variable to update. +|`name`|Form parameter|__String__. Name of the variable. +|===== + +//// |`identifier` __String__| ID or name of the variable. Include the variable ID as a path parameter in the request body. |`name` __String__ | New name for the variable. Specify a name if you want to rename the variable. |`Operation` __String__ a| Specify the update operation type. The following options are available: @@ -157,24 +179,17 @@ Principal attributes such as user and user group. These attributes are applicabl * `priority` __Optional__ + The priority assigned to this value. Applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. |===== - +//// === Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/3242b54c-69bc-4ff0-97cf-f99a2216b616/update' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "operation": "REPLACE", - "name": "TableVar", - "values": [ - { - "value": "MyOrg`", - "org_identifier": "MyOrg1" - } - ] + "name": "formula_variable_test" }' ---- @@ -182,67 +197,70 @@ 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 +* Deleting values from variables === 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 +.3+|`variable_assignment` 2+| Properties for assigning values to variables. +|`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. +Adds new values if it's a list type. Use this operation type if you want to add new attributes to the variable. * `REPLACE` + Replaces the existing attributes with new values. -|===== +* `REMOVE` + +Removes the values assigned to the variable specified in the API request. Only list type variable values are removed. +* `CLEAR` + +Removes the current conditions assigned to a variable. + +.6+|`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. === Request example [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 +271,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 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 +297,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 +311,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 +360,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..5630fb321 --- /dev/null +++ b/modules/ROOT/pages/webhooks-lb-schedule.adoc @@ -0,0 +1,737 @@ += Webhooks for Liveboard schedule events +: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 the webhook endpoint such as your internal marketing or incident management app. With webhooks, you no longer need to manually handle the data received in email notifications from ThoughtSpot. + +To automate sending scheduled Liveboard notifications to a webhook endpoint, ThoughtSpot administrators must configure the following: + +* A webhook communication channel. + +Use the following REST APIs to set and view communication channel preferences: +** `POST /api/rest/2.0/system/preferences/communication-channels/configure` +** `POST /api/rest/2.0/system/preferences/communication-channels/search` +* A webhook for the Liveboard schedule event to enable programmatic communication between the target application and ThoughtSpot. + +To create and manage webhook APIs, use the following APIs: +** `POST /api/rest/2.0/webhooks/create` +** `POST /api/rest/2.0/webhooks/delete` +** `POST /api/rest/2.0/webhooks/search` +** `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + +[NOTE] +==== +In the current release: + +* REST APIs support webhook channel configuration for `LIVEBOARD_SCHEDULE` events only. +* You can configure only one webhook for the Liveboard schedule event per Org. +==== + +== Get started +The webhooks setup for Liveboard Schedule events involves the following steps: + +* xref:webhooks-lb-schedule.adoc#_configure_webhook_communication_channel[Configuring a webhook communication channel at the cluster or Org level]. +* xref:webhooks-lb-schedule.adoc#_configure_a_webhook_for_liveboard_schedule_event[Creating a webhook to listen to the Liveboard schedule events]. +* xref:webhooks-lb-schedule.adoc#_verify_the_webhook_payload[Verifying the webhook payload]. + +=== Before you begin + +Check your application environment for the following prerequisites: + +* Ensure that you have access to a ThoughtSpot instance with the required permissions to set communication channel preferences, create and manage webhooks, and schedule Liveboard jobs. + +If your instance has Role-based Access Control (RBAC) enabled, you must have the `CAN_MANAGE_WEBHOOKS` privilege to create and manage webhooks. +* Ensure that the REST APIs for setting communication channel preference and configuring webhooks are enabled on your instance. +* To allow outbound traffic from the ThoughtSpot to the webhook endpoint, add the webhook destination URL to the xref:security-settings.adoc#csp-connect-src[CSP connect-src] allowlist in ThoughtSpot. +* Add the ThoughtSpot application URL as a trusted host in your Webhook destination endpoint/app. + +=== Configure a webhook communication channel for the Liveboard Schedule event + +To create a webhook communication channel, use the system REST APIs. + +In the current release, ThoughtSpot supports configuring a communication channel only for Liveboard schedule events. + +==== 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 sample request for setting 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": "docstest", + "operation": "REPLACE", + "preferences": [ + { + "event_type": "LIVEBOARD_SCHEDULE", + "channels": [ + "WEBHOOK" + ] + } + ] + } + ] +}' +---- + +===== API response +If the request is successful, the API returns a 204 response indicating successful operation. + +==== View the communication channel preferences + +To review and audit the communication channel preferences set on your instance, send a `POST` request to the `POST /api/rest/2.0/system/preferences/communication-channels/search` API endpoint. + +to audit, review, or display the current communication channel settings, ensuring compliance or troubleshooting notification issues. + +===== 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": "docstest", + "event_types": [ + "LIVEBOARD_SCHEDULE" + ] + } + ] +}' +---- + +If the request is successful, the API returns a 204 response indicating successful operation. + +===== Example response + +The following example shows the communication preferences configured for the specified event type at the cluster level: + +[source,JSON] +---- +{ + "cluster_preferences": [], + "org_preferences": [ + { + "org": { + "id": "0", + "name": "Primary" + }, + "preferences": [] + }, + { + "org": { + "id": "1532970882", + "name": "nr-git-prod" + }, + "preferences": [ + { + "event_type": "LIVEBOARD_SCHEDULE", + "channels": [ + "EMAIL", + "WEBHOOK" + ] + } + ] + }, + { + "org": { + "id": "2100019165", + "name": "docstest" + }, + "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": "docstest" + }, + "preferences": [ + { + "event_type": "LIVEBOARD_SCHEDULE", + "channels": [ + "WEBHOOK" + ] + } + ] + } + ] +} +---- + +=== Configure a webhook for the Liveboard Schedule event + +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 making 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": "docstest" + }, + "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": "docstest", + "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": "docstest" + }, + "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 properties of a webhook, 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` + +* `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 properties of a webhook: + +[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 + +[width="100%" cols="2,4"] +[options='header'] +|===== +|`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, ThoughtSpot details of the deleted webhook. + +[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 + +If the webhook channel is configured for Liveboard schedule events and a webhook is created for the event, it can be applied to all Liveboard schedules in an Org. + +For testing purposes, you can use a URL from the link:https://webhook.site/[Webhook site, window=_blank] and check the payload when the Liveboard schedule event is triggered. You can also monitor the incoming requests on the link:https://webhook-test-server-263n.onrender.com/[Webhooks test site, window=_blank]. + +When a Liveboard schedule event is triggered based on the conditions defined in the schedule, the webhook sends the payload to the configured endpoint. Depending upon the Liveboard job settings, the payload includes metadata such as webhook communication channel ID, recipient details, Liveboard schedule details, event properties, and a link to the Liveboard. + +[source,JSON] +---- +{ + "actor": { + "actorType": "SYSTEM" + }, + "data": { + "aiHighlights": "", + "channelID": "873dd4e2-6493-490d-a649-ba9ea66b11f5", + "channelType": "webhook", + "communicationType": "LiveboardSchedules", + "msgUniqueId": "881fd036-5b2e-4e34-928c-e3839b2e5765", + "recipients": [ + { + "email": "UserA@thoughtspot.com", + "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "locale": "en_GB", + "name": "UserA", + "type": "USER" + } + ], + "scheduleDetails": { + "authorId": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "creationTime": "2025-10-21T12:51:01Z", + "description": "", + "emailIds": [], + "exportRequest": { + "liveboard_params": { + "layout_type": "LIVEBOARD", + "liveboard_viz_selection": { + "complete_liveboard": true + }, + "personalised_view_id": "", + "print_document_params": { + "include_cover_page": false, + "include_filter_page": false, + "pageFooterParams": { + "include_logo": true, + "include_page_number": true, + "text": "" + } + }, + "visualization_format_options": { + "truncate_tables": true + } + }, + "object_type": "LIVEBOARD", + "output_type": "PDF", + "pdf_params": { + "orientation": "LANDSCAPE", + "page_size": "A4" + }, + "request_type": "SCHEDULE" + }, + "fileFormat": "pdf", + "groupIds": [], + "name": "Sales-LB - Custom", + "runId": "dc232f76-064f-4f40-a771-7c4a6f6a2906", + "scheduleId": "e4bd8b30-dfad-490a-b09a-a50e969f7d32", + "status": "SCHEDULED", + "userIds": [], + "viewInfo": null + } + }, + "eventId": "n.820c00f9-d7ef-48e9-ab08-2ec1a48de0ab", + "eventType": "LIVEBOARD_SCHEDULE", + "metadataObject": { + "id": "daeef525-926a-44fc-9dbf-7dfa993d913a", + "name": "Sales-LB", + "objectType": "LIVEBOARD", + "url": "https://my.thoughtspot.cloud/?utm_source=scheduled-pinboard&utm_medium=email&orgId=2100019165#/pinboard/daeef525-926a-44fc-9dbf-7dfa993d913a" + }, + "schemaVersion": "1.0", + "source": { + "applicationName": "ThoughtSpot", + "applicationUrl": "hhttps://my.thoughtspot.cloud", + "instanceId": "672764c0-dc60-11ee-a6bf-13c83", + "orgId": "2100019165" + }, + "timestamp": "2025-10-21T13:05:31Z" +} +---- + +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. + +== 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 c7fb5dec7..b20615371 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -19,6 +19,25 @@ ThoughtSpot now enables developers to define custom action in their embed code t Code based custom actions are flexible across Orgs and groups as well. +=== Webhooks for Liveboard schedule events + +You can now configure a xref:webhooks-lb-schedule.adoc[webhook for Liveboard schedule events] [beta betaBackground]^Beta^ to automate notifications to external applications. This feature allows you to send Liveboard reports directly to a webhook endpoint, such as your internal marketing or incident management app, at a scheduled frequency. It eliminates the need to manually process data from email notifications and gives you full control over how the data is handled in your downstream workflows. + +This feature is currently in beta and is not enabled by default. To enable it on your instance, contact ThoughtSpot Support + +=== Template variables for publishing +You can now configure formula variables and assign these variables to your metadata. The variable APIs also include several enhancements to streamline variable creation and update workflows. + +For more information, see xref:variables.adoc[Variables documentation]. + +=== 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 From a70408bfdd251c87c24b4c620161d00b8dcd0d35 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 23 Oct 2025 16:53:16 +0530 Subject: [PATCH 09/29] changelog merge --- modules/ROOT/pages/api-changelog.adoc | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index ba42a9fec..9b8cf2936 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,13 +8,15 @@ 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]. -== Version 1.43.0, October 2025 - +== November 2025 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|*Code based custom actions* - -|==== +|[tag greenBackground]#NEW FEATURE# a|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. == Version 1.42.0, October 2025 From bc5f0680e655c1e9934c611e4b83e23f33125af8 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 23 Oct 2025 17:09:44 +0530 Subject: [PATCH 10/29] version update --- src/configs/doc-configs.js | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index e376d7e95..57cffd8ba 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -34,10 +34,16 @@ module.exports = { DEV: 'dev', }, VERSION_DROPDOWN: [ + { + label: '10.14.0.cl', + link: ' ', + subLabel: 'Cloud (Latest)', + }, { label: '10.13.0.cl', link: ' ', subLabel: 'Cloud (Latest)', + iframeUrl: 'https://developer-docs-10-13-0-cl.vercel.app/docs/', }, { label: '10.12.0.cl', From cea459579558582f7de7d29fdcd9eda4097619b2 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 23 Oct 2025 21:07:17 +0530 Subject: [PATCH 11/29] variables update --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 2 +- modules/ROOT/pages/variables.adoc | 43 +++++++++++--------- 2 files changed, 24 insertions(+), 21 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index dac50f494..d643f04e6 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -23,7 +23,7 @@ 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: +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` diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc index f7fa64e85..5bd938ed8 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -6,8 +6,7 @@ :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. Before publishing an object to other Orgs, define variables for each Org and assign these variables to the metadata object properties. - +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. [IMPORTANT] ==== @@ -17,11 +16,11 @@ Note the following enhancements and breaking changes introduced in ThoughtSpot C ** You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in the API request to the `/api/rest/2.0/template/variables/create` API endpoint . ** The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `POST /api/rest/2.0/template/variables/update-values` API endpoint. -* Variables update + +* Variables update and value assignement + ** The `/api/rest/2.0/template/variables/update` 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` API endpoint. ** The resource path for updating multiple variable values has changed from `POST /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, the `POST /api/rest/2.0/template/variables/update-values` API endpoint. -* Variables search + +* Variable search+ ** Filtering API response by `EDITABLE_METADATA_AND_VALUES` output format is no longer supported. @@ -56,19 +55,19 @@ To define variables for connection properties per user or user group. This varia Formula variables. |`name`| __String__. Name of the variable. For example, `schema_var`. Note that the name must be unique across all Orgs within the instance. |`sensitive` __Optional__ |__Boolean__. Indicates if the variable contains sensitive values such as passwords. -|`data_type`|__String__. Variable data type. Required parameter for formula variables. Supported data types are: +|`data_type` a|__String__. Variable data type. Required parameter for formula variables. Supported data types are: * `VARCHAR` + String. For example, "East", "Administrator", "Secure", "2025-10-23" -* `INT32` +* `INT32` + 32-bit integer data type. For example, 100,-42 -* `INT64` +* `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` + Date format. For example, 2025-10-20. -* `DATE_TIME` +* `DATE_TIME` + Date with time stamp. For example, 2025-10-20 14:30:00. |===== //// @@ -129,7 +128,7 @@ Note the variable ID. To update a variable or properties of a variable, use the following REST APIs: -* `+++POST /api/rest/2.0/template/variables/{identifier}/update+++` +* +++POST /api/rest/2.0/template/variables/{identifier}/update+++ + Allows updating the properties of a variable. @@ -203,7 +202,7 @@ The API endpoint allows: * Adding new values to variables * Replacing existing values -* Deleting values from variables +* Resetting values === Request parameters @@ -213,29 +212,33 @@ In your `POST` request body, you can include the following parameters: [options='header'] |===== |Parameter|Properties|Description -.3+|`variable_assignment` 2+| Properties for assigning values to variables. +.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 if it's a list type. Use this operation type if you want to add new attributes to the variable. +Adds new values. Use this operation type if you want to add new attributes to the variable. * `REPLACE` + Replaces the existing attributes with new values. * `REMOVE` + -Removes the values assigned to the variable specified in the API request. Only list type variable values are removed. -* `CLEAR` + -Removes the current conditions assigned to a variable. +Removes the values assigned to the variable. For example, you can remove the values assigned to a formula variable configured for an Org. +* `RESET + +Resets all values at the variable level. For example, if a variable is assigned to multiple entities such as Org, user, or user group, the reset operation clears the values assigned to the variable for all entities. -.6+|`variable_value_scope` 2+| Set the scope for variable values. +.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.| +__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. +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 @@ -272,7 +275,7 @@ 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 details + -Details such as variable type, ID, and name pattern. For name pattern search, specify partial name of the variable. For wildcard search, use `%`. +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 + From c9afc3601394c03ae112e1724de3c3c53137b1ba Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 23 Oct 2025 21:41:42 +0530 Subject: [PATCH 12/29] edits --- modules/ROOT/pages/variables.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc index 5bd938ed8..d63adb045 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -14,13 +14,13 @@ Note the following enhancements and breaking changes introduced in ThoughtSpot C * Variable creation + ** You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in the API request to the `/api/rest/2.0/template/variables/create` API endpoint . -** The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `POST /api/rest/2.0/template/variables/update-values` API endpoint. +** The variable creation `/api/rest/2.0/template/variables/create` API allows creating a variable, but doesn't support assigning values to the variable. To assign values, use the `POST /api/rest/2.0/template/variables/update-values` API endpoint. * Variables update and value assignement + ** The `/api/rest/2.0/template/variables/update` 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` API endpoint. ** The resource path for updating multiple variable values has changed from `POST /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, the `POST /api/rest/2.0/template/variables/update-values` API endpoint. -* Variable search+ +* Variable search + ** Filtering API response by `EDITABLE_METADATA_AND_VALUES` output format is no longer supported. From 1838bea1c6c195c12c19881196a6f190cb6eb35b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 23 Oct 2025 22:16:05 +0530 Subject: [PATCH 13/29] edits --- modules/ROOT/pages/webhooks-lb-schedule.adoc | 4 +++- modules/ROOT/pages/whats-new.adoc | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/webhooks-lb-schedule.adoc b/modules/ROOT/pages/webhooks-lb-schedule.adoc index 5630fb321..a7465c916 100644 --- a/modules/ROOT/pages/webhooks-lb-schedule.adoc +++ b/modules/ROOT/pages/webhooks-lb-schedule.adoc @@ -1,4 +1,4 @@ -= Webhooks for Liveboard schedule events += Webhooks for Liveboard schedule events[beta betaBackground]^Beta^ :toc: true :toclevels: 3 @@ -6,6 +6,8 @@ :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. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 39a43278a..b086fd432 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -19,9 +19,9 @@ ThoughtSpot now enables developers to define custom action in their embed code t Code based custom actions are flexible across Orgs and groups as well. -=== Webhooks for Liveboard schedule events +=== Webhooks for Liveboard schedule events [beta betaBackground]^Beta^ -You can now configure a xref:webhooks-lb-schedule.adoc[webhook for Liveboard schedule events] [beta betaBackground]^Beta^ 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. +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 From 3b6fa41a5b6ee5e5b9363a17bcec860891ab5077 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 23 Oct 2025 23:39:31 +0530 Subject: [PATCH 14/29] runtime parameters update --- modules/ROOT/pages/api-changelog.adoc | 9 +++-- modules/ROOT/pages/runtime-parameters.adoc | 40 +++++++++++++++++----- 2 files changed, 37 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index d8227eac2..91f7c7437 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -11,14 +11,17 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For in == November 2025 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The following enumerations are available for code based custom actions: +|[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# | *Host event* +The HostEvent.UpdateParameters₹ event now includes 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 diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 08b47f4eb..c126e09d2 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -106,10 +106,12 @@ After loading the embedded object, Parameters can be adjusted using the link:htt liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: "Date List Param", value: 1656914873 + isVisibleToUser: true }, { name: "Integer Range Param", - value: 10 + value: 10, + isVisibleToUser: false } ]) ---- @@ -120,25 +122,45 @@ In Spotter embed, updating Parameters via host and embed events may not work. ==== === Show or hide Parameter chips in embedded sessions -Parameter values can be set or overridden using multiple methods. In some use cases, you may want to hide the Parameter chips from ThoughtSpot's UI, while in other cases you may want to show the chips. +Parameter values can be set or overridden using multiple methods. In some use cases, you may want to hide the Parameter chips from the ThoughtSpot 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: +To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading ThoughtSpot's page using one of the following methods: -* Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK (Recommended) -* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK) +* Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK +* To update the parameter's value after the page is loaded, use `HostEvent.UpdateParameters`. + +When you apply an override via `HostEvent.UpdateParameters`, the chips are hidden by default. However, its value in ThoughtSpot's visualizations will be updated accordingly. To define the criterion explicitly for showing or hiding the Parameter chip, use the `isVisibleToUser` boolean attribute in the host event specification. -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. ++ +[source,JavaScript] +---- +liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ + name: "Integer Range Param", + value: "10", + isVisibleToUser: false +}]) +---- + +* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK) ==== Show Parameter chip in ThoughtSpot UI -To show the parameter chip from ThoughtSpot's user interface, update the Parameter's value with `HostEvent.UpdateParameters` after the page has loaded. The Parameter chip will then be shown and updated with each new value passed via the event. +To show the parameter chip from ThoughtSpot's user interface, use the `isVisibleToUser` attribute in the `HostEvent.UpdateParameters` specification and trigger the event after the page has loaded. The Parameter chip will then be shown and updated with each new value passed via the event. + +[source,JavaScript] +---- +liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ + name: "Integer Range Param", + value: "10", + isVisibleToUser: false +}]) +---- [width="100%" cols="5,5,8"] [options='header'] |===== |Parameter chip|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` -|Hidden|Yes| Possible -|Shown| No| Possible +|Hidden|Yes| Yes, if the `isVisibleToUser` attribute is set to `false` in the host event code. +|Shown| No| Yes, if the `isVisibleToUser` attribute is set to `true` in the host event code. |===== == Apply Parameter overrides via REST API From 2774001614b779607f3567c4d93b234fe59d3229 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 24 Oct 2025 08:43:02 +0530 Subject: [PATCH 15/29] typo fixes --- modules/ROOT/pages/runtime-parameters.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index c126e09d2..7b43bcde4 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -127,8 +127,8 @@ Parameter values can be set or overridden using multiple methods. In some use ca ==== Hide Parameter chips To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading ThoughtSpot's page using one of the following methods: -* Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK -* To update the parameter's value after the page is loaded, use `HostEvent.UpdateParameters`. + +* Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK. +* To update the parameter's value after the page is loaded, use `HostEvent.UpdateParameters` in the Visual Embed SDK. + When you apply an override via `HostEvent.UpdateParameters`, the chips are hidden by default. However, its value in ThoughtSpot's visualizations will be updated accordingly. To define the criterion explicitly for showing or hiding the Parameter chip, use the `isVisibleToUser` boolean attribute in the host event specification. + @@ -141,7 +141,7 @@ liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ }]) ---- -* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK) +* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK). ==== Show Parameter chip in ThoughtSpot UI To show the parameter chip from ThoughtSpot's user interface, use the `isVisibleToUser` attribute in the `HostEvent.UpdateParameters` specification and trigger the event after the page has loaded. The Parameter chip will then be shown and updated with each new value passed via the event. From 3043e34a00ab0dd6ca29e4de05e45cb62bdc4d04 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 24 Oct 2025 09:26:31 +0530 Subject: [PATCH 16/29] typo fixes --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 10 +++++----- modules/ROOT/pages/variables.adoc | 11 ++++++----- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index d643f04e6..a273ef782 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -54,16 +54,16 @@ The following enhancements are introduced in variable API endpoints: Variable creation:: -* You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in the API request to the `/api/rest/2.0/template/variables/create` API endpoint . -* The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `POST /api/rest/2.0/template/variables/update-values` API endpoint. +* You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in your API request to the `/api/rest/2.0/template/variables/create` endpoint. +* The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. Variables update:: [tag redBackground]#BREAKING CHANGE# -* The `/api/rest/2.0/template/variables/update` 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` API endpoint. -* The resource path for updating multiple variable values has changed from `POST /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, the `POST /api/rest/2.0/template/variables/update-values` API endpoint. +* 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 to allow users to filter API response by variable values. +* 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]. diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc index d63adb045..27e3694af 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -13,15 +13,16 @@ Variables allow you to define dynamic placeholders for specific properties of me Note the following enhancements and breaking changes introduced in ThoughtSpot Cloud 10.14.l0.cl release: * Variable creation + -** You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in the API request to the `/api/rest/2.0/template/variables/create` API endpoint . -** The variable creation `/api/rest/2.0/template/variables/create` API allows creating a variable, but doesn't support assigning values to the variable. To assign values, use the `POST /api/rest/2.0/template/variables/update-values` API endpoint. +** You can now create formula variables. To create a formula variable, use the `FORMULA_VARIABLE` type in your API request to the `/api/rest/2.0/template/variables/create` endpoint. +** The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. -* Variables update and value assignement + -** The `/api/rest/2.0/template/variables/update` 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` API endpoint. -** The resource path for updating multiple variable values has changed from `POST /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, the `POST /api/rest/2.0/template/variables/update-values` API endpoint. +* Variables update and value assignment + +** The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/{identifier}/update`. To update a variable, use the `POST /api/rest/2.0/template/variables/update` endpoint. +** The resource path for updating multiple variable values has changed from `/api/rest/2.0/template/variables/{identifier}/update` to `/api/rest/2.0/template/variables/update-values`. To assign values to one or several variables, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. * Variable search + +** The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. ** Filtering API response by `EDITABLE_METADATA_AND_VALUES` output format is no longer supported. ThoughtSpot recommends updating your application setup and workflows to avoid operational issues in your environment. From 02d40546c3e75a633ae42964e5174382cc728e6f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 24 Oct 2025 10:53:53 +0530 Subject: [PATCH 17/29] edits --- modules/ROOT/pages/runtime-parameters.adoc | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 7b43bcde4..93a6dd6cb 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -122,44 +122,44 @@ In Spotter embed, updating Parameters via host and embed events may not work. ==== === Show or hide Parameter chips in embedded sessions -Parameter values can be set or overridden using multiple methods. In some use cases, you may want to hide the Parameter chips from the ThoughtSpot UI, while in other cases, you may want to show the chips. + +Parameter values can be set or overridden using multiple methods. In some cases, you may want to hide Parameter chips from the ThoughtSpot UI, while in other cases, you may want to show them. ==== Hide Parameter chips To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading ThoughtSpot's page using one of the following methods: * Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK. +* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK). * To update the parameter's value after the page is loaded, use `HostEvent.UpdateParameters` in the Visual Embed SDK. + -When you apply an override via `HostEvent.UpdateParameters`, the chips are hidden by default. However, its value in ThoughtSpot's visualizations will be updated accordingly. To define the criterion explicitly for showing or hiding the Parameter chip, use the `isVisibleToUser` boolean attribute in the host event specification. - + When you apply an override via `HostEvent.UpdateParameters`, the chip is hidden by default, but the value in ThoughtSpot’s visualizations is updated accordingly. To control the Parameter chip visibility, use the `isVisibleToUser` boolean attribute in the host event specification. + [source,JavaScript] ---- liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: "Integer Range Param", - value: "10", + value: 10, isVisibleToUser: false }]) ---- -* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK). - ==== Show Parameter chip in ThoughtSpot UI -To show the parameter chip from ThoughtSpot's user interface, use the `isVisibleToUser` attribute in the `HostEvent.UpdateParameters` specification and trigger the event after the page has loaded. The Parameter chip will then be shown and updated with each new value passed via the event. +To show the parameter chip in the ThoughtSpot UI, set the `isVisibleToUser` attribute in the `HostEvent.UpdateParameters` specification and trigger the event after the page has loaded. The Parameter chip will then be displayed and updated with each new value passed via the event. [source,JavaScript] ---- liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: "Integer Range Param", - value: "10", - isVisibleToUser: false + value: 10, + isVisibleToUser: true }]) ---- [width="100%" cols="5,5,8"] [options='header'] |===== -|Parameter chip|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` -|Hidden|Yes| Yes, if the `isVisibleToUser` attribute is set to `false` in the host event code. + +|Parameter chip behavior|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` +|Hidden|Yes| Possible. with `isVisibleToUser` attribute is set to `false` in the host event code. |Shown| No| Yes, if the `isVisibleToUser` attribute is set to `true` in the host event code. |===== From 992a7d68ecfa7adb79ae1fb261b529ebec2c7257 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 24 Oct 2025 10:55:15 +0530 Subject: [PATCH 18/29] typo fixes --- modules/ROOT/pages/runtime-parameters.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 93a6dd6cb..78286e9f2 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -159,8 +159,8 @@ liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ |===== |Parameter chip behavior|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` -|Hidden|Yes| Possible. with `isVisibleToUser` attribute is set to `false` in the host event code. -|Shown| No| Yes, if the `isVisibleToUser` attribute is set to `true` in the host event code. +|Hidden|Yes| Possible +|Shown| No| Possible |===== == Apply Parameter overrides via REST API From af93fe41a1aa5bb3178797d51c5be65e4f8a364b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 24 Oct 2025 12:18:03 +0530 Subject: [PATCH 19/29] edits --- modules/ROOT/pages/api-changelog.adoc | 4 +- modules/ROOT/pages/runtime-parameters.adoc | 62 ++++++++++++++++++---- 2 files changed, 55 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 91f7c7437..762bbdbb2 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -19,8 +19,8 @@ The following enumerations are available for code based custom actions: 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# | *Host event* -The HostEvent.UpdateParameters₹ event now includes 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]. +|[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 diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 78286e9f2..d7f9fbe23 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -123,16 +123,57 @@ In Spotter embed, updating Parameters via host and embed events may not work. === Show or hide Parameter chips in embedded sessions -Parameter values can be set or overridden using multiple methods. In some cases, you may want to hide Parameter chips from the ThoughtSpot UI, while in other cases, you may want to show them. +Parameter values can be set or overridden using the following methods: + +* Using the `runtimeParameters` property in ThoughtSpot's Visual Embed SDK. +* By triggering the `HostEvent.UpdateParameters` event in the SDK. To do this, load the page with parameters applied to the Liveboard or Answer, then override the parameter value using `HostEvent.UpdateParameters`. +* By applying a Parameter override directly in the URL (if you are not using the Visual Embed SDK). + +When a parameter is set or its value is overridden, the parameter chip is hidden from the embedded page view by default. + +In some cases, you may want the Parameter chips to show in the ThoughtSpot UI after they are set or modified. To support such use cases, the Visual Embed SDK allows you to set the `isVisibleToUser` attribute in the `HostEvent.UpdateParameters` event payload. + +The following table describes parameter chip behavior in common configuration scenarios: + +==== Parameter chip behavior +[width="100%" cols="5,7,8,8"] +[options='header'] +|===== +| How Parameter is set/updated +| Parameter chip behaviour (default) +| Update via `HostEvent.UpdateParameters`? +| Can make the chip visible via `isVisibleToUser`? + +| Via `runtimeParameters` in the Visual Embed SDK +| Hidden +| Possible +| No. + + +| Via URL parameter override +| Hidden +| Possible +| No. + +| Via `HostEvent.UpdateParameters` +| Hidden +| Possible +| Yes. The chip visibility can be overridden by setting `isVisibleToUser` to `true`. + +| Set initially via `runtimeParameters` in the SDK, and then updated via `HostEvent.UpdateParameters` +| Hidden +| Possible +| No. The chip visibility cannot be overridden by setting `isVisibleToUser` to `true`. +|===== ==== Hide Parameter chips -To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading ThoughtSpot's page using one of the following methods: +To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading the ThoughtSpot page using one of the following methods: + +* Via `runtimeParameters` in Visual Embed SDK. +* By applying a Parameter override directly in the URL (if you are not using the Visual Embed SDK). + +Additionally, setting the `isVisibleToUser` attribute to `false` in the `HostEvent.UpdateParameters` code in the SDK will hide the chip for the modified parameter. -* Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK. -* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK). -* To update the parameter's value after the page is loaded, use `HostEvent.UpdateParameters` in the Visual Embed SDK. + - When you apply an override via `HostEvent.UpdateParameters`, the chip is hidden by default, but the value in ThoughtSpot’s visualizations is updated accordingly. To control the Parameter chip visibility, use the `isVisibleToUser` boolean attribute in the host event specification. -+ [source,JavaScript] ---- liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ @@ -143,7 +184,7 @@ liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ ---- ==== Show Parameter chip in ThoughtSpot UI -To show the parameter chip in the ThoughtSpot UI, set the `isVisibleToUser` attribute in the `HostEvent.UpdateParameters` specification and trigger the event after the page has loaded. The Parameter chip will then be displayed and updated with each new value passed via the event. +To show the parameter chip in the ThoughtSpot UI, set the `isVisibleToUser` attribute to `true` in the `HostEvent.UpdateParameters` code and trigger the event after the page has loaded. The Parameter chip will then be displayed and updated with each new value passed via the event. [source,JavaScript] ---- @@ -153,7 +194,7 @@ liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ isVisibleToUser: true }]) ---- - +//// [width="100%" cols="5,5,8"] [options='header'] |===== @@ -163,6 +204,9 @@ liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ |Shown| No| Possible |===== +//// + + == Apply Parameter overrides via REST API You can apply Parameter overrides to a Liveboard or Answer using REST v1 and v2 API endpoints. From 6dc91368b9542b2ccae6bd6608d394013cb437e4 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 24 Oct 2025 15:52:00 +0530 Subject: [PATCH 20/29] edits --- modules/ROOT/pages/get-started-tse.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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]. |===== From 2bfa6a285473209853bbde8589119e9147239583 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 29 Oct 2025 13:45:57 +0530 Subject: [PATCH 21/29] webhooks review comments incorporation --- modules/ROOT/pages/webhooks-lb-schedule.adoc | 470 +++++++++++++++---- 1 file changed, 375 insertions(+), 95 deletions(-) diff --git a/modules/ROOT/pages/webhooks-lb-schedule.adoc b/modules/ROOT/pages/webhooks-lb-schedule.adoc index a7465c916..068d62d3c 100644 --- a/modules/ROOT/pages/webhooks-lb-schedule.adoc +++ b/modules/ROOT/pages/webhooks-lb-schedule.adoc @@ -1,4 +1,4 @@ -= Webhooks for Liveboard schedule events[beta betaBackground]^Beta^ += Webhooks for Liveboard schedule events [beta betaBackground]^Beta^ :toc: true :toclevels: 3 @@ -6,19 +6,17 @@ :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. +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 the webhook endpoint such as your internal marketing or incident management app. With webhooks, you no longer need to manually handle the data received in email notifications from ThoughtSpot. +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, ThoughtSpot administrators must configure the following: +To automate sending scheduled Liveboard notifications to a webhook endpoint, the following configuration is required: -* A webhook communication channel. + +* Ensure that "webhook" is selected as a communication channel for your Org or at the cluster level for all Orgs on your instance. Ensure that “webhook” is selected as the communication channel for your Org, or at the cluster level for all Orgs in your instance.+ Use the following REST APIs to set and view communication channel preferences: ** `POST /api/rest/2.0/system/preferences/communication-channels/configure` ** `POST /api/rest/2.0/system/preferences/communication-channels/search` @@ -50,15 +48,13 @@ Check your application environment for the following prerequisites: * Ensure that you have access to a ThoughtSpot instance with the required permissions to set communication channel preferences, create and manage webhooks, and schedule Liveboard jobs. + If your instance has Role-based Access Control (RBAC) enabled, you must have the `CAN_MANAGE_WEBHOOKS` privilege to create and manage webhooks. -* Ensure that the REST APIs for setting communication channel preference and configuring webhooks are enabled on your instance. +* Ensure that the REST APIs for setting communication channel preference and configuring webhooks are enabled on your instance. If the APIs are not available on your instance, contact ThoughtSpot Support. * To allow outbound traffic from the ThoughtSpot to the webhook endpoint, add the webhook destination URL to the xref:security-settings.adoc#csp-connect-src[CSP connect-src] allowlist in ThoughtSpot. * Add the ThoughtSpot application URL as a trusted host in your Webhook destination endpoint/app. -=== Configure a webhook communication channel for the Liveboard Schedule event - -To create a webhook communication channel, use the system REST APIs. +=== Configure a webhook communication channel -In the current release, ThoughtSpot supports configuring a communication channel only for Liveboard schedule events. +To create a webhook communication channel for the Liveboard Schedule event, use the channel preference REST API. ==== Create a webhook communication channel @@ -79,7 +75,8 @@ a|__String__. Type of the event for which communication channels are configured. __Array of strings__. Communication channel for the event type specified in the request. Valid values are: + * `EMAIL` -* `WEBHOOK` + +* `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: @@ -93,21 +90,21 @@ __Array of strings__. Define the following parameters to set communication chann __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` + +** `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` - 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. @@ -130,7 +127,7 @@ curl -X POST \ }' ---- -The following example shows the sample request for setting communication channel preference at the Org level. +The following example shows the request body for setting a communication channel preference at the Org level. [source,cURL] ---- @@ -141,7 +138,7 @@ curl -X POST \ --data-raw '{ "org_preferences": [ { - "org_identifier": "docstest", + "org_identifier": "testOrg1", "operation": "REPLACE", "preferences": [ { @@ -157,13 +154,11 @@ curl -X POST \ ---- ===== API response -If the request is successful, the API returns a 204 response indicating successful operation. +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 `POST /api/rest/2.0/system/preferences/communication-channels/search` API endpoint. - -to audit, review, or display the current communication channel settings, ensuring compliance or troubleshooting notification issues. +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 @@ -177,10 +172,10 @@ __Optional__ a|__Array of strings__. To filter API response by event type, speci | `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`. +* `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 @@ -213,7 +208,7 @@ curl -X POST \ --data-raw '{ "org_preferences": [ { - "org_identifier": "docstest", + "org_identifier": "testOrg1", "event_types": [ "LIVEBOARD_SCHEDULE" ] @@ -258,7 +253,7 @@ The following example shows the communication preferences configured for the spe { "org": { "id": "2100019165", - "name": "docstest" + "name": "testOrg1" }, "preferences": [ { @@ -283,7 +278,7 @@ The following example shows the preferences returned for a specific Org: { "org": { "id": "2100019165", - "name": "docstest" + "name": "testOrg1" }, "preferences": [ { @@ -298,7 +293,7 @@ The following example shows the preferences returned for a specific Org: } ---- -=== Configure a webhook for the Liveboard Schedule event +=== Configure a webhook To configure webhooks for the Liveboard schedule event, use the webhook REST API. @@ -320,7 +315,7 @@ __Optional__ a|__String__. Description text for the webhook | `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 making HTTP requests to the webhook endpoint. +Defines authentication method and credentials that ThoughtSpot will use when sending HTTP requests to the webhook endpoint. Specify the authentication type. @@ -384,7 +379,7 @@ If the webhook creation is successful, the API returns the following response: "description": "Webhook for Liveboard schedule", "org": { "id": "2100019165", - "name": "docstest" + "name": "testOrg1" }, "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d", "url_params": null, @@ -446,7 +441,7 @@ curl -X POST \ --data-raw '{ "record_offset": 0, "record_size": 50, - "org_identifier": "docstest", + "org_identifier": "testOrg1", "event_type": "LIVEBOARD_SCHEDULE" }' ---- @@ -465,7 +460,7 @@ If the API request is successful, ThoughtSpot returns the webhook configuration "description": "Webhook for Liveboard schedule", "org": { "id": "2100019165", - "name": "docstest" + "name": "testOrg1" }, "url": "https://webhook.site/view/6643eba5-9d3e-42a1-85e0-bb686ba1524d/29c02fc2-c1c6-4b20-8d62-e8d51cf8dfb3", "url_params": null, @@ -497,7 +492,7 @@ If the API request is successful, ThoughtSpot returns the webhook configuration ==== Update the properties of a webhook -To update the properties of a webhook, send a `POST` request to the `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint. +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 @@ -512,6 +507,7 @@ 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` + @@ -521,7 +517,7 @@ Signature verification parameters for the webhook endpoint to verify the authent ===== Example request -The following example shows the request body for updating the properties of a webhook: +The following example shows the request body for updating the name, description text, and endpoint URL of a webhook object: [source,cURL] ---- @@ -548,11 +544,14 @@ If the API request is successful, the API returns a 204 response code indicating 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 @@ -573,7 +572,7 @@ curl -X POST \ ===== Example response -If the API request is successful, ThoughtSpot details of the deleted webhook. +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] ---- @@ -611,95 +610,276 @@ If the API request is successful, ThoughtSpot details of the deleted webhook. === Verify the webhook payload -If the webhook channel is configured for Liveboard schedule events and a webhook is created for the event, it can be applied to all Liveboard schedules in an Org. +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 -For testing purposes, you can use a URL from the link:https://webhook.site/[Webhook site, window=_blank] and check the payload when the Liveboard schedule event is triggered. You can also monitor the incoming requests on the link:https://webhook-test-server-263n.onrender.com/[Webhooks test site, window=_blank]. +The `WebhookTargetObjectInfo` schema defines the object for which the event is generated. -When a Liveboard schedule event is triggered based on the conditions defined in the schedule, the webhook sends the payload to the configured endpoint. Depending upon the Liveboard job settings, the payload includes metadata such as webhook communication channel ID, recipient details, Liveboard schedule details, event properties, and a link to the Liveboard. +[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": { - "aiHighlights": "", - "channelID": "873dd4e2-6493-490d-a649-ba9ea66b11f5", - "channelType": "webhook", - "communicationType": "LiveboardSchedules", - "msgUniqueId": "881fd036-5b2e-4e34-928c-e3839b2e5765", - "recipients": [ - { - "email": "UserA@thoughtspot.com", - "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "locale": "en_GB", - "name": "UserA", - "type": "USER" - } - ], "scheduleDetails": { - "authorId": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "creationTime": "2025-10-21T12:51:01Z", - "description": "", - "emailIds": [], + "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": "LIVEBOARD", + "layout_type": "VISUALIZATION", + "personalised_view_id": "a8118b21-4581-4315-8833-39b2aa5be542", "liveboard_viz_selection": { - "complete_liveboard": true + "complete_liveboard": false, + "included_viz_id": [ + "efe80e30-ca82-4b83-a9c0-7371be45d3e6", + "957c9e37-0352-40ca-8d07-fb056a91332d" + ] }, - "personalised_view_id": "", "print_document_params": { - "include_cover_page": false, - "include_filter_page": false, + "include_cover_page": true, + "include_filter_page": true, "pageFooterParams": { "include_logo": true, "include_page_number": true, - "text": "" + "text": "footer" } }, "visualization_format_options": { "truncate_tables": true } }, - "object_type": "LIVEBOARD", - "output_type": "PDF", - "pdf_params": { - "orientation": "LANDSCAPE", - "page_size": "A4" - }, "request_type": "SCHEDULE" }, "fileFormat": "pdf", - "groupIds": [], - "name": "Sales-LB - Custom", - "runId": "dc232f76-064f-4f40-a771-7c4a6f6a2906", - "scheduleId": "e4bd8b30-dfad-490a-b09a-a50e969f7d32", "status": "SCHEDULED", - "userIds": [], - "viewInfo": null - } - }, - "eventId": "n.820c00f9-d7ef-48e9-ab08-2ec1a48de0ab", - "eventType": "LIVEBOARD_SCHEDULE", - "metadataObject": { - "id": "daeef525-926a-44fc-9dbf-7dfa993d913a", - "name": "Sales-LB", - "objectType": "LIVEBOARD", - "url": "https://my.thoughtspot.cloud/?utm_source=scheduled-pinboard&utm_medium=email&orgId=2100019165#/pinboard/daeef525-926a-44fc-9dbf-7dfa993d913a" - }, - "schemaVersion": "1.0", - "source": { - "applicationName": "ThoughtSpot", - "applicationUrl": "hhttps://my.thoughtspot.cloud", - "instanceId": "672764c0-dc60-11ee-a6bf-13c83", - "orgId": "2100019165" - }, - "timestamp": "2025-10-21T13:05:31Z" + "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` + @@ -729,6 +909,106 @@ Source of the webhook payload trigger. This includes the ThoughtSpot application 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] From 8de6bca44d75d19120490aa8ec7e80c20cbaa73a Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 29 Oct 2025 14:48:35 +0530 Subject: [PATCH 22/29] SCAL-278492 fix --- modules/ROOT/pages/runtime-filters.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 81cec2c87..c77028b36 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -24,6 +24,7 @@ Pass filter properties as query parameters in the URL. ==== * The runtime filters operation returns an error if the URL exceeds 2000 characters. * Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. +* When a Model has a column alias defined, ensure that the column name in the runtime filters reference the underlying base column name and not the column alias. ==== === Runtime filter properties From 28b46ce426a8afc99557a5ad9ea0b62ce89609d1 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 29 Oct 2025 14:49:12 +0530 Subject: [PATCH 23/29] runtimeParam breaking change note and other fixes --- modules/ROOT/pages/runtime-parameters.adoc | 16 +++++++++++++--- modules/ROOT/pages/whats-new.adoc | 14 +++++++++++++- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index d7f9fbe23..874f4e8b1 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -99,7 +99,7 @@ Note the following behavior in Spotter embedding: * If a user adds a Parameter to an answer through the edit flow, Spotter may drop this Parameter and any formulas using it in follow-up interactions. This means Parameters added in this way are not guaranteed to persist in subsequent conversational steps. === Adjust Parameter values using SDK events -After loading the embedded object, Parameters can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateparameters[HostEvent.UpdateParameters] event: +After loading the embedded object, Parameters can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateparameters[HostEvent.UpdateParameters] event as shown in these examples: [source,JavaScript] ---- @@ -107,8 +107,13 @@ liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: "Date List Param", value: 1656914873 isVisibleToUser: true - }, - { + } +]) +---- + +[source,JavaScript] +---- +liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: "Integer Range Param", value: 10, isVisibleToUser: false @@ -166,6 +171,11 @@ The following table describes parameter chip behavior in common configuration sc | No. The chip visibility cannot be overridden by setting `isVisibleToUser` to `true`. |===== +[NOTE] +==== +If a Parameter chip is hidden, you cannot make it visible by changing the `isVisibleToUser` setting. +==== + ==== Hide Parameter chips To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading the ThoughtSpot page using one of the following methods: diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index b086fd432..28e2122ef 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -30,6 +30,19 @@ You can now configure formula variables and assign these variables to your metad For more information, see xref:variables.adoc[Variables documentation]. + +=== Parameter chip visibility configuration + +The `HostEvent.UpdateParameters` event now includes an `isVisibleToUser` flag to control the visibility of Parameter chips on embedded ThoughtSpot pages. + +Previously, the Parameter chip displaying behavior was inconsistent, because some embed types would keep the chips visible via an override using `HostEvent.UpdateParameters`, while other embed types would hide the chips when the Parameter is overridden. With the new enhancement, the `isVisibleToUser` attribute in `HostEvent.UpdateParameters` is set to `false` by default for all pages, to ensure consistent behavior. + +Impact on your current implementation:: +With the new enhancement, the embedded pages that previously kept the parameter visible after an override via `HostEvent.UpdateParameters`, will now hide it unless the `isVisibleToUser` attribute is explicitly set to `true`. This new behavior introduces a breaking change for any implementation relying on the previous default chip visibility behavior. + +Recommended action:: +Developers who want to retain the old behavior must update their integration to pass the `isVisibleToUser: true` setting when updating Parameters via `HostEvent.UpdateParameters`. + === Visual Embed SDK For information about the new features and enhancements introduced in Visual Embed SDK version 1.43.0, see xref:api-changelog.adoc[Visual Embed changelog]. @@ -37,7 +50,6 @@ For information about the new features and enhancements introduced in Visual Emb === 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 From c79437940594674f6270fac2224a55bf3762ae46 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 29 Oct 2025 15:18:47 +0530 Subject: [PATCH 24/29] example fix --- modules/ROOT/pages/webhooks-lb-schedule.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/webhooks-lb-schedule.adoc b/modules/ROOT/pages/webhooks-lb-schedule.adoc index 068d62d3c..5d32220b7 100644 --- a/modules/ROOT/pages/webhooks-lb-schedule.adoc +++ b/modules/ROOT/pages/webhooks-lb-schedule.adoc @@ -238,7 +238,7 @@ The following example shows the communication preferences configured for the spe { "org": { "id": "1532970882", - "name": "nr-git-prod" + "name": "testOrg" }, "preferences": [ { From 23a24182b447237434572effa714fc7fa14628a4 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 29 Oct 2025 15:19:31 +0530 Subject: [PATCH 25/29] CBCA --- .../ROOT/pages/callback-response-payload.adoc | 6 +- .../ROOT/pages/code-based-custom-actions.adoc | 437 ++++++++++++++++++ modules/ROOT/pages/common/nav.adoc | 10 +- .../ROOT/pages/custom-actions-callback.adoc | 1 - modules/ROOT/pages/custom-actions-url.adoc | 3 +- modules/ROOT/pages/custom-actions-viz.adoc | 1 - .../ROOT/pages/custom-actions-worksheet.adoc | 1 - modules/ROOT/pages/custom-actions.adoc | 91 +++- .../ROOT/pages/customize-actions-menu.adoc | 6 + modules/ROOT/pages/whats-new.adoc | 2 + 10 files changed, 538 insertions(+), 20 deletions(-) create mode 100644 modules/ROOT/pages/code-based-custom-actions.adoc 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..eebe72ab7 --- /dev/null +++ b/modules/ROOT/pages/code-based-custom-actions.adoc @@ -0,0 +1,437 @@ += Code based custom actions +:toc: true +:toclevels: 2 + +:page-title: Code based custom actions +:page-pageid: code-based-custom-action +:page-description: You can add custom buttons or menu items in your ThoughtSpot code to the ThoughtSpot UI to let your application users to analyze insights and trigger an action on the data. + +Code-based custom actions are custom menu items that you define within the application's code through the Visual Embed SDK. These actions are executed when the user clicks on them. +Unlike the custom actions through the UI, this allows users to define custom actions using a few lines of code, specifying exactly where (target object) and how (placement in the UI) they should appear. +This makes it easier to implement these actions across Orgs, and also supports advanced customization. + +These custom actions add a new menu item to one of the following UI elements in an Answer, Liveboard, visualization, or in the Spotter interface: + +* the primary menu bar (except for Spotter) +* the **More** options menu image:./images/icon-more-10px.png[the more options menu] +* the contextual menu that appears when a user right-clicks on an Answer or visualization (except for Liveboard) + +[NOTE] +If a custom action for the primary menu bar is defined both in the ThoughtSpot UI and in the application code, only the action created through the UI will be shown. + + +=== Implementation of custom actions through the Visual Embed SDK + +Custom Actions can be embedded through the Visual Embed SDK in the following two ways: + +**Via the init function** + +* Custom actions can be registered globally during SDK initialization. +* This allows the action to be reused across multiple embedded objects. + +**Via individual embed functions** + +* Custom actions can be defined at the time of embedding a specific component like a Liveboard (LiveboardEmbed). +* This provides more granular control over where and how these actions are shown. + + +=== Components of a code based custom action interface + +[width="100%" cols="4,5"] +[options='header'] +|=== +|parameter|description + +|`name`|_String._ Display name for the custom action. +|`id`|_String._ Unique identifier for the action. +|`position` a|Position where the action should be rendered. Valid values include: + + +* `CustomActionsPosition.MENU` +* `CustomActionsPosition.PRIMARY` +* `CustomActionsPosition.CONTEXTMENU` + +|`target` a|The target object type where the action applies. Valid values include: + + +* `CustomActionTarget.LIVEBOARD` +* `CustomActionTarget.VIZ` +* `CustomActionTarget.ANSWER` +* `CustomActionTarget.SPOTTER` + +|`metadataIds` a|_Optional_. Metadata-based filtering for actions. Valid values include: + + +* `answerIds`:__Array of Strings.__ Applicable Answer ids. Unique identifier (GUID) for the Answer. +* `liveboardIds`: __Array of Strings.__ Applicable Liveboard ids. Unique identifier (GUID) for the Liveboard. +* `vizIds`: __Array of Strings.__ Applicable Viz ids. Unique identifier (GUID) for the Visualization. +|`dataModelIds` a|__Array of Strings.__ Unique identifier (GUID) for the data Model `modelIds` or column names `modelColumnNames`. +|`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 `modelId` 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 columnIds are provided, the custom action will be displayed only on visualizations that are created using the specified columnIds. + +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. +* If model2 does not have a col2, this will result in an error. + +[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 modelId or columnNames are 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 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 `modelId` 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.PRIMARY, + target: CustomActionTarget.SPOTTER, + dataModelIds: { + modelIds: ['model1'] + }, +}, ]; +---- + + +When a `vizId` or `answerId` is specified, custom actions will not be displayed in Spotter. Instead, custom actions will only be shown on the specific answers or visualizations whose IDs have been provided. This configuration is mostly used in full application embed scenarios. + +[source,javascript] +---- +const customActions = [{ + name: 'CA1', + id: 'ca1', + position: CustomActionPosition.PRIMARY, + target: CustomActionTarget.SPOTTER, + metadataIds: { + vizIds: ['viz1'] + }, +}, ]; +---- + +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.PRIMARY, + 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 f583de45d..aa2b430be 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -86,6 +86,7 @@ ***** link:{{navprefix}}/css-variables-reference[CSS variables reference] ***** link:{{navprefix}}/customize-icons[Customize icons] ***** link:{{navprefix}}/customize-text[Customize text strings] +**** link:{{navprefix}}/code-based-custom-action[Code based custom actions] ***** link:{{navprefix}}/theme-builder-doc[Theme builder ^Beta^] *** link:{{navprefix}}/filters-overview[Filters overview] @@ -97,13 +98,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] diff --git a/modules/ROOT/pages/custom-actions-callback.adoc b/modules/ROOT/pages/custom-actions-callback.adoc index 300c46dd3..3a7df7ccd 100644 --- a/modules/ROOT/pages/custom-actions-callback.adoc +++ b/modules/ROOT/pages/custom-actions-callback.adoc @@ -15,7 +15,6 @@ Callback custom actions allow you to get data payloads from an embedded ThoughtS * Callback custom actions are supported on embedded ThoughtSpot instances only and require a ThoughtSpot Embedded Edition license. * Users with developer or admin privileges can create a callback custom action in the Developer portal. * Developers can set a callback action as a global or local action. -* To access callback actions, users must have the **New Answer Experience** enabled on their application instance. * Users with edit permissions to a Model or visualization can add a local callback action to a visualization or Answer of their choice. * Developers must register the callback in the Visual Embed SDK and define data classes and functions to parse and process the JSON data payload retrieved from the callback event. -- diff --git a/modules/ROOT/pages/custom-actions-url.adoc b/modules/ROOT/pages/custom-actions-url.adoc index e298883e6..eb1b719fb 100644 --- a/modules/ROOT/pages/custom-actions-url.adoc +++ b/modules/ROOT/pages/custom-actions-url.adoc @@ -16,8 +16,7 @@ ThoughtSpot allows you to add a custom action to trigger a data payload to a spe * Any ThoughtSpot user with admin or developer privileges can create URL custom actions in the Developer portal. * URL actions are available on both embedded and standalone ThoughtSpot instances and do not require ThoughtSpot Embedded Edition license. * Developers can set a URL action as a global or local action. -* Developers can limit custom action access to a specific user group. -* To access a URL action, users must have the **New Answer Experience** enabled. +* Developers can limit custom action access to a specific user group. * For URL actions to work in the embedded mode, you must add the URL domain to the CORS and CSP connect-src allowlist. * Only ThoughtSpot users with edit permissions to a Model or visualization can add a URL action to a Model, visualization, or saved Answer. -- diff --git a/modules/ROOT/pages/custom-actions-viz.adoc b/modules/ROOT/pages/custom-actions-viz.adoc index 0dc50f6b4..552581493 100644 --- a/modules/ROOT/pages/custom-actions-viz.adoc +++ b/modules/ROOT/pages/custom-actions-viz.adoc @@ -21,7 +21,6 @@ If you have access to a custom action, ThoughtSpot lets you perform the followin Perform the following checks: -* The link:https://docs.thoughtspot.com/cloud/latest/answer-experience-new[new Answer experience, window=_blank] is enabled on your cluster. * The custom action is available on your instance and is set as *Local*. * You have edit permission to modify the visualization or saved Answer. diff --git a/modules/ROOT/pages/custom-actions-worksheet.adoc b/modules/ROOT/pages/custom-actions-worksheet.adoc index 3a3579d2b..fe009ca8a 100644 --- a/modules/ROOT/pages/custom-actions-worksheet.adoc +++ b/modules/ROOT/pages/custom-actions-worksheet.adoc @@ -16,7 +16,6 @@ When you assign a custom action to a Model, ThoughtSpot adds it to the Answers g * Make sure the custom actions are set as *Local*. * Make sure you have edit permissions to modify the Model. -* Make sure the link:https://docs.thoughtspot.com/cloud/latest/answer-experience-new[new Answer experience, window=_blank] is enabled on your cluster. == Assign a custom action to a Model diff --git a/modules/ROOT/pages/custom-actions.adoc b/modules/ROOT/pages/custom-actions.adoc index a7f011da7..7bf7db71e 100644 --- a/modules/ROOT/pages/custom-actions.adoc +++ b/modules/ROOT/pages/custom-actions.adoc @@ -6,23 +6,27 @@ ThoughtSpot provides a set of standard menu commands and buttons, controlled via xref:embed-actions.adoc[actions]. -Custom actions add a new menu item to one of the following UI elements in an Answer or Liveboard visualization: +Custom actions add a new menu item to one of the following UI elements: * the primary menu bar * the **More** options menu image:./images/icon-more-10px.png[the more options menu] * the contextual menu that appears when a user right-clicks on an Answer or visualization + -[NOTE] -==== -The link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_vizpointclick[VizPointClick HostEvent] behaves in the same way as a context menu custom action, but fires immediately on a click rather than from the right-click context menu. -==== +Custom actions in ThoughtSpot can be implemented in two different ways: +* Custom actions through the UI +* Custom actions done programmatically (code based) + + +//// Custom actions are implemented in two parts: * *Within ThoughtSpot*, define the new menu item and its placement * *In the embedding app*, build code to receive the event and data when the user clicks the menu action. +//// -== Define custom actions in ThoughtSpot + +== Custom actions in the ThoughtSpot UI You must xref:customize-actions-menu.adoc[create custom actions] in the **Develop** > **Customizations** > **Custom actions** page of the ThoughtSpot UI. After a custom action has been created, there are several options for assigning how and where the custom action will appear: @@ -31,8 +35,75 @@ After a custom action has been created, there are several options for assigning * xref:custom-actions-worksheet.adoc[Assign custom actions to a Model] * xref:custom-actions-edit.adoc[Set the menu position of a custom action] +== Code based custom actions +Code-based custom actions are custom menu items that you define within the application's code through the Visual Embed SDK. + +These custom actions add a new menu item to one of the following UI elements in an Answer, Liveboard, visualization, or in the Spotter interface: + +* the primary menu bar (except for Spotter) +* the **More** options menu image:./images/icon-more-10px.png[the more options menu] +* the contextual menu that appears when a user right-clicks on an Answer or visualization (not for Liveboard) + +For more information, see xref:code-based-custom-actions.adoc[Code based custom actions]. + == Ways for embedding apps to receive custom actions -* xref:custom-actions-callback.adoc[Callback actions] + -Pass data and metadata from ThoughtSpot to the embedding page as an event. -* xref:custom-actions-url.adoc[URL actions] + -POST data directly to a specific web page or API endpoint destination. +**xref:custom-actions-callback.adoc[Callback actions]** + + +* Pass data and metadata from ThoughtSpot to the embedding page as an event. + +* Can be done through the ThoughtSpot UI or in the code through ThoughtSpot's Visual Embed SDK. + +**xref:custom-actions-url.adoc[URL actions]** + + +* POST data directly to a specific web page or API endpoint destination. + +* Only available through the ThoughtSpot UI. + +== Features comparison + +[width="100%" cols="4,5,5"] +[options='header'] +|=== +|Feature|Custom actions through the UI|Code based custom actions + +|Type|Callback actions + +URL based actions|Callback actions +|Scope|Answers + +Visualizations +Models +| +Answers + +Liveboards + +Visualizations + +Models +|Sharing|User groups|User groups +Orgs +|Liveboard menu|-|Primary menu + +More menu +|Visualization menu|Primary menu + +More menu + +Contextual menu|Primary menu + +More menu + +Contextual menu +|Answer menu|Primary menu + +More menu + +Contextual menu|Primary menu + +More menu + +Contextual menu +|Spotter |-|More menu + +Contextual menu +|=== + diff --git a/modules/ROOT/pages/customize-actions-menu.adoc b/modules/ROOT/pages/customize-actions-menu.adoc index 29a2ee0c5..2ce475de4 100644 --- a/modules/ROOT/pages/customize-actions-menu.adoc +++ b/modules/ROOT/pages/customize-actions-menu.adoc @@ -8,6 +8,12 @@ The custom actions feature in ThoughtSpot allows users to push data to external applications. To allow ThoughtSpot users to quickly act on the data they analyze, custom actions must be pre-configured in their setup. ThoughtSpot users with developer or admin privileges can create various types of custom actions in the **Develop ** tab and make them available on a saved Answer or visualization page. +[NOTE] +==== +The link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_vizpointclick[VizPointClick HostEvent] behaves in the same way as a context menu custom action, but fires immediately on a click rather than from the right-click context menu. +==== + + [div boxDiv boxFullWidth] -- +++
Feature highlights
+++ diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 28e2122ef..6860aefbb 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -19,6 +19,8 @@ ThoughtSpot now enables developers to define custom action in their embed code t Code based custom actions are flexible across Orgs and groups as well. +For more information, see xref:code-based-custom-actions.adoc[Code based custom actions] + === Webhooks for Liveboard schedule events [beta betaBackground]^Beta^ You can now configure a xref:webhooks-lb-schedule.adoc[webhook for Liveboard schedule events] to automate notifications to external applications. This feature allows you to send Liveboard reports directly to a webhook endpoint, such as your internal marketing or incident management app, at a scheduled frequency. It eliminates the need to manually process data from email notifications and gives you full control over how the data is handled in your downstream workflows. From cdd755d069faeae7e763205b296c02cbece01fa5 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 29 Oct 2025 15:41:17 +0530 Subject: [PATCH 26/29] CBCA1 --- .../ROOT/pages/code-based-custom-actions.adoc | 46 +++++++++++-------- modules/ROOT/pages/common/nav.adoc | 1 - 2 files changed, 27 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/code-based-custom-actions.adoc b/modules/ROOT/pages/code-based-custom-actions.adoc index eebe72ab7..57047dc9f 100644 --- a/modules/ROOT/pages/code-based-custom-actions.adoc +++ b/modules/ROOT/pages/code-based-custom-actions.adoc @@ -62,7 +62,7 @@ Custom Actions can be embedded through the Visual Embed SDK in the following two * `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`. +|`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 : [`modelId::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). |=== @@ -255,7 +255,7 @@ const customActions = [{ ---- -When columnIds are provided, the custom action will be displayed only on visualizations that are created using the specified columnIds. +When `modelColumnNames` are provided, the custom action will be displayed only on visualizations that are created using the specified `modelColumnNames`. In this example: @@ -286,7 +286,6 @@ 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. -* If model2 does not have a col2, this will result in an error. [source,javascript] ---- @@ -336,7 +335,7 @@ const customActions = [{ ---- -When a modelId or columnNames are specified, the custom action will be displayed for all answers which use the specified model. +When a `modelIds` is specified, the custom action will be displayed for all answers which use the specified model. In this example: @@ -360,45 +359,53 @@ const customActions = [{ }, ]; ---- -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. +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 on ans1 for users who are a part of org1, and also a member grp1. +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', + name: "CA1", id: 'ca1', position: CustomActionsPosition.PRIMARY, target: CustomActionTarget.ANSWER, metadataIds: { answerIds: ['ans1'], }, - groupId: ['grp1'], - orgId: ['org1'], + dataModelIds: { + modelColumnNames: ["model1::col1"], + }, }, ]; - ---- -=== Code based custom action for Spotter +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. -When a `modelId` 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. +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: CustomActionPosition.PRIMARY, - target: CustomActionTarget.SPOTTER, - dataModelIds: { - modelIds: ['model1'] + position: CustomActionsPosition.PRIMARY, + target: CustomActionTarget.ANSWER, + metadataIds: { + answerIds: ['ans1'], }, + groupId: ['grp1'], + orgId: ['org1'], }, ]; + ---- +=== Code based custom action for Spotter -When a `vizId` or `answerId` is specified, custom actions will not be displayed in Spotter. Instead, custom actions will only be shown on the specific answers or visualizations whose IDs have been provided. This configuration is mostly used in full application embed scenarios. +When a `modelId` 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] ---- @@ -407,12 +414,13 @@ const customActions = [{ id: 'ca1', position: CustomActionPosition.PRIMARY, target: CustomActionTarget.SPOTTER, - metadataIds: { - vizIds: ['viz1'] + 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, diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index aa2b430be..8f7e34007 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -86,7 +86,6 @@ ***** link:{{navprefix}}/css-variables-reference[CSS variables reference] ***** link:{{navprefix}}/customize-icons[Customize icons] ***** link:{{navprefix}}/customize-text[Customize text strings] -**** link:{{navprefix}}/code-based-custom-action[Code based custom actions] ***** link:{{navprefix}}/theme-builder-doc[Theme builder ^Beta^] *** link:{{navprefix}}/filters-overview[Filters overview] From 368bd0d83d49ad7c99194d8399c88ee7ae4efb72 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 29 Oct 2025 17:42:22 +0530 Subject: [PATCH 27/29] CBCA2 --- modules/ROOT/pages/code-based-custom-actions.adoc | 4 ++-- modules/ROOT/pages/theme-builder.adoc | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/code-based-custom-actions.adoc b/modules/ROOT/pages/code-based-custom-actions.adoc index 57047dc9f..4788d7809 100644 --- a/modules/ROOT/pages/code-based-custom-actions.adoc +++ b/modules/ROOT/pages/code-based-custom-actions.adoc @@ -412,7 +412,7 @@ When a `modelId` is specified, custom actions will be displayed on all answers a const customActions = [{ name: 'CA1', id: 'ca1', - position: CustomActionPosition.PRIMARY, + position: CustomActionPosition.MENU, target: CustomActionTarget.SPOTTER, dataModelIds: { modelIds: ['model1'] @@ -434,7 +434,7 @@ In this example, for a user who is part of org1 and grp1, const customActions = [{ name: 'CA1', id: 'ca1', - position: CustomActionPosition.PRIMARY, + position: CustomActionPosition.MENU, target: CustomActionTarget.SPOTTER, dataModelIds: { modelIds: ['model1'] 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 From 0e8e6b9661c056458db2ac4a9ee17101b6ea62d3 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 30 Oct 2025 11:09:14 +0530 Subject: [PATCH 28/29] CBCA3 --- modules/ROOT/pages/code-based-custom-actions.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/code-based-custom-actions.adoc b/modules/ROOT/pages/code-based-custom-actions.adoc index 4788d7809..27c92b8d0 100644 --- a/modules/ROOT/pages/code-based-custom-actions.adoc +++ b/modules/ROOT/pages/code-based-custom-actions.adoc @@ -62,7 +62,7 @@ Custom Actions can be embedded through the Visual Embed SDK in the following two * `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 : [`modelId::columnName`]. +|`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). |=== @@ -230,7 +230,7 @@ const customActions = [{ ---- -When `modelId` is passed in the `dataModelIds`, then the custom action is show for all visualization which are using the columns of the specified model. +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: @@ -405,7 +405,7 @@ const customActions = [{ === Code based custom action for Spotter -When a `modelId` 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. +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] ---- From a3bc89dd0b976db82ae276c6fac8818151d4905b Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Fri, 31 Oct 2025 08:22:17 +0530 Subject: [PATCH 29/29] clickhouse-email-custom --- modules/ROOT/pages/connections.adoc | 26 ++++++++++++++++++++ modules/ROOT/pages/customize-email-apis.adoc | 1 - 2 files changed, 26 insertions(+), 1 deletion(-) 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/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: