diff --git a/modules/ROOT/pages/about-rest-apis.adoc b/modules/ROOT/pages/about-rest-apis.adoc index 608f729d1..3ac6e7ca6 100644 --- a/modules/ROOT/pages/about-rest-apis.adoc +++ b/modules/ROOT/pages/about-rest-apis.adoc @@ -26,11 +26,22 @@ ThoughtSpot users with Developer or Administrator privileges can access the REST * To try out the xref:rest-api-v1.adoc[REST API v1 endpoints], click **REST Playground v1**. + * To access the xref:rest-api-v2.adoc[REST API v2 Playground], click **REST Playground v2.0**. +== Rate limits for API requests +To ensure API stability, optimize resource usage, and maintain service quality for all users, ThoughtSpot limits the number of public API requests allowed per client to prevent excessive requests from reaching application servers. + +By default, on instances running 26.2.0.cl and later, a global rate limit of 100 requests per second per client IP is enforced at the cluster level for all public APIs. This limit is applied per client IP across all public APIs combined, not per endpoint. If a client IP exceeds this combined rate limit, a burst of 10 additional API requests is allowed before rejecting the requests with the 'HTTP 429: Too Many Requests' error. + +For async status endpoints such as `/api/rest/2.0/metadata/tml/async/status`, up to 100 requests per minute per client IP are allowed, with a burst of 100 requests before requests are rejected with an HTTP 429 error. + +These rate limits are enforced by default on all ThoughtSpot instances. Currently, rate limits are applied at the cluster level; Org-level rate limits are not supported. + +To update rate limits or adjust the rate limit settings for your dev or prod environment, contact ThoughtSpot Support. + +//ThoughtSpot administrators can monitor logs, add or update rate limits via TSCLI, and adjust these settings for different environments (dev or prod) as required. + == API endpoints For a complete list of API endpoints and information about how to make an API call to these endpoints, see the following reference pages: * xref:rest-api-reference.adoc[REST API v1 Reference] * xref:rest-api-v2-reference.adoc[REST API v2.0 Reference] -//// - diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 4022f96ea..9792b332c 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,63 @@ 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.45.0, February 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|**Spotter enhancements ** + +You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, Chat history, and a new chat prompt interface. + +* To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. +* To use Auto mode, set the `worksheetId` to `_spotter_data_source_discovery_id`. +* To enable Chat history, set `enablePastConversationsSidebar` to `true`. + +For more information, see xref:embed-spotter.adoc[Embedding Spotter] and xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Features available with Spotter 3 experience]. + +Events:: + +* `EmbedEvent.AddToCoaching` for the *Add to coaching* workflow in a Spotter conversation session +* `HostEvent.AddToCoaching` to trigger the *Add to coaching* action in a Spotter conversation session. +* `HostEvent.StartNewSpotterConversation` to trigger the action to start a new chat session with Spotter. + +|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + + +Styling and grouping:: + +* The `isLiveboardStylingAndGrouping` attribute, used for enabling the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated attribute, `isLiveboardStylingAndGrouping` continues to work, we recommend switching to the new configuration setting. +* The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: +** `Action.MoveToGroup` for the **Move to Group** menu action. +** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. +** `Action.CreateGroup` for the *Create Group* menu action. +** `Action.UngroupLiveboardGroup` for the **Ungroup Liveboard Group** menu action. + +Filter chip masking:: +The `showMaskedFilterChip` boolean parameter is now available to control the visibility of masked filter chips on a Liveboard. When set to `true`, if a Liveboard is shared with a user who has restricted access due to column-level security, the filter chip corresponding to those inaccessible columns will be displayed as masked to that user. When set to `false`, the filter chip for inaccessible columns will not be visible to the user. ++ +For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards]. ++ +The `showMaskedFilterChip` setting is also available in full application embedding. + +|[tag greenBackground]#NEW FEATURE# a|**Publishing objects** + +The following action IDs are available for the data publishing menu actions in the *Data workspace* page: + +* `Action.Publish` for *Publish* +* `Action.ManagePublishing` for *Manange publishing* +* `Action.Unpublish` foe *Unpublish* +* `Action.Parameterize` for *Parameterize* +|[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** + +To handle errors in the embedding workflows, the SDK includes the following features: + +* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, `NETWORK` error. +* `EmbedErrorCodes` enum with specific error codes for programmatic error handling +* `EmbedErrorDetailsEvent` interface for structured error event handling + +For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. +|==== + == Version 1.44.x, January 2026 [width="100%" cols="1,4"] @@ -35,6 +92,7 @@ Emits when an API call matching the conditions defined in `interceptUrls` is det For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. |==== + == Version 1.43.0, November 2025 [width="100%" cols="1,4"] |==== diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 3489b7ec9..e8301160f 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -63,7 +63,7 @@ **** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] **** link:{{navprefix}}/embed-a-viz[Embed a visualization] *** link:{{navprefix}}/embed-ai-search-analytics[Embed AI Search and Analytics] -**** link:{{navprefix}}/embed-spotter[Embed Spotter] +**** link:{{navprefix}}/embed-spotter[Embed Spotter experience] **** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent] **** link:{{navprefix}}/embed-nls[Embed Natural Language Search (legacy interface)] *** link:{{navprefix}}/full-embed[Embed full application] @@ -215,19 +215,25 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/webhooks-kpi[Webhook for KPI alerts] *** link:{{navprefix}}/webhooks-lb-schedule[Webhook for Liveboard schedule events ^Beta^] +* MCP Servers and Tools +** link:{{navprefix}}/SpotterCode[SpotterCode for IDEs] +*** link:{{navprefix}}/integrate-SpotterCode[Integrating SpotterCode] +*** link:{{navprefix}}/spottercode-prompting-guide[SpotterCode prompting guide] +** link:{{navprefix}}/mcp-integration[ThoughtSpot MCP server] + * link:{{navprefix}}/development-and-deployment[Deployment and integration] ** link:{{navprefix}}/development-and-deployment[Development and deployment] *** link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects overview] -*** link:{{navprefix}}/variables[Custom variables ^Beta^] +*** link:{{navprefix}}/variables[Custom variables] *** link:{{navprefix}}/git-integration[Deploy with Git] **** link:{{navprefix}}/git-configuration[Configure Git integration] **** link:{{navprefix}}/git-api[Version Control REST APIs] **** link:{{navprefix}}/guid-mapping[GUID mapping] *** link:{{navprefix}}/deploy-with-tml-apis[Deploy with TML APIs] **** link:{{navprefix}}/modify-tml[TML modification] -*** link:{{navprefix}}/publish-data-overview[Publish content to Orgs ^Beta^] -**** link:{{navprefix}}/parameterze-metdata[Parameterize metadata ^Beta^] -**** link:{{navprefix}}/publish-to-orgs[Publish objects to Orgs ^Beta^] +*** link:{{navprefix}}/publish-data-overview[Publish content to Orgs] +**** link:{{navprefix}}/parameterze-metdata[Parameterize metadata] +**** link:{{navprefix}}/publish-to-orgs[Publish objects to Orgs] ** link:{{navprefix}}/multi-tenancy[Multi-tenancy] *** link:{{navprefix}}/orgs[Multi-tenancy with Orgs] @@ -235,10 +241,10 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/single-tenant-data-models[Single-tenant data models with Orgs] *** link:{{navprefix}}/orgs-api-op[Org administration] ** link:{{navprefix}}/tse-cluster[Cluster maintenance and upgrade] + * Integration with external tools ** link:{{navprefix}}/external-tool-script-integration[External tools and scripts] ** link:{{navprefix}}/pendo-integration[Pendo integration with embed] -** link:{{navprefix}}/mcp-integration[MCP server integration] ** link:{{navprefix}}/sf-integration[Integration with Salesforce] ** link:{{navprefix}}/vercel-integration[Vercel integration] * Additional references diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index 1e5f6a9c3..3338d9e7c 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -235,11 +235,92 @@ To download a personalized view of the Liveboard, specify the view name in the ` * Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. ==== -==== File Format +==== File Formats -The default `file_format` is PDF. For PDF downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. You can also download the report in PNG format. +The default `file_format` is *CSV*. -For PNG downloads, you can now define +[NOTE] +If you do not have .csv downloads enabled for your ThoughtSpot instance, select either `PDF` or `PNG` `file_format` to successfully download the report. Using any other format will cause the API to return an error. + + +For *CSV* downloads [earlyAccess eaBackground]#Early Access#, + +* Each visualization is exported as a separate .csv file. +* If multiple visualizations are selected, the downloaded report is a single compressed .zip file containing all .CSV files. +* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. +* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. + +===== Sample API payload for CSV downloads + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", +"file_format": "CSV", +"tab_identifiers": [ +"bc6d6fb8-1e06-4617-b02f-51745e6933a6" +] +}' +---- + +For *XLSX* downloads [earlyAccess eaBackground]#Early Access#, + +* Visualization is exported as an Excel workbook (.xlsx). +* If multiple visualizations are selected, the downloaded report is a single Excel workbook (.xlsx) containing each visualization in their individual tab. +* A maximum of 255 tabs per .xlsx workbook are allowed. +* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. +* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. +* Unlike the pivot tables that are downloaded for any pivot table Answer in the ThoughtSpot UI, pivot tables generated in .xlsx workbooks using this API endpoint are exported as their underlying raw data. The .xlsx currently does not support the pivot table format. + +===== Sample API payload for XLSX downloads + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", +"file_format": "XLSX", +"visualization_identifiers": [ +"254c6e30-680c-41ea-aa4d-bb059f745462" +] +}' +---- + +For *PDF* downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. + +===== Sample API payload for XLSX downloads + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", +"file_format": "PDF", +"visualization_identifiers": [ +"254c6e30-680c-41ea-aa4d-bb059f745462" +], +"pdf_options": { +"include_cover_page": true, +"include_custom_logo": true, +"include_filter_page": true, +"include_page_number": true, +"page_orientation": "LANDSCAPE", +"page_footer_text": "Sample footer text" +} +}' +---- + +For *PNG* downloads, you can now define * `image_resolution` [earlyAccess eaBackground]#Early Access# * `image_scale` [earlyAccess eaBackground]#Early Access# @@ -250,13 +331,14 @@ 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`. +** 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*. ==== -==== Example +===== Sample API payload for PNG downloads + [source,cURL] ---- curl -X POST \ @@ -264,23 +346,25 @@ curl -X POST \ -H 'Authorization: Bearer {access-token}'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", "file_format": "PNG", - "visualization_identifiers": [ - "9bd202f5-d431-44bf-9a07-b4f7be372125", - "9bd202f5-d431-44bf-9a07-b4f7be372125", - "9bd202f5-d431-44bf-9a07-b4f7be372125" + "tab_identifiers": [ + "bc6d6fb8-1e06-4617-b02f-51745e6933a6" ], "png_options": { - "include_cover_page": true, - "include_filter_page": true + "include_cover_page": null, + "include_filter_page": null, + "personalised_view_id": null, + "image_resolution": 1920, + "image_scale": 100, + "include_header": true } }' ---- ==== Override filters -If the Liveboard has filters applied and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. +If the Liveboard has filters applied, and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. [source,JSON] ---- diff --git a/modules/ROOT/pages/embed-ai-analytics.adoc b/modules/ROOT/pages/embed-ai-analytics.adoc index 1641ce495..3454144ac 100644 --- a/modules/ROOT/pages/embed-ai-analytics.adoc +++ b/modules/ROOT/pages/embed-ai-analytics.adoc @@ -4,72 +4,290 @@ :page-title: Embed AI Search and Analytics :page-pageid: embed-ai-search-analytics -:page-description: To embed ThoughtSpot Spotter and conversational analytics experience in your app, you can use the `SpotterEmbed` or `SpotterAgentEmbed` SDK library. +:page-description: To embed the ThoughtSpot Spotter and conversational analytics experience in your app, you can use the `SpotterEmbed` or `SpotterAgentEmbed` SDK components. -ThoughtSpot Spotter provides an interactive AI-powered Search and conversational analytics experience for its application users. With ThoughtSpot Spotter, users can query data in plain language, ask follow-up questions, and get insights directly from their data. ThoughtSpot also provides an agentic version of Spotter for a more advanced experience with context-based conversations and responses for deeper analysis. +Spotter provides an interactive AI-powered search and conversational analytics experience for ThoughtSpot application users. It empowers users to ask questions in natural language and analyzes data to generate business-ready insights instantly. -== Embed components -ThoughtSpot provides two distinct SDK libraries to embed Spotter capabilities in your app: +ThoughtSpot supports three experience modes: Spotter Classic, Spotter Agent (Spotter 2), and Spotter 3. Spotter 3 supports several new features, agentic analytics, and provides an enhanced user experience. + +[width="100%" cols="2,4"] +[options="header"] +|==== +|Version| Supported features +|Spotter 3 [tag purpleBackground]#Early Access# +a| Spotter 3 is the latest and most advanced version of Spotter. + +**Key features and user experience**: + +In addition to the Spotter Classic and Spotter 2 capabilities, Spotter 3 supports the following features and enhancements to improve the AI search and analytics experience: + +* Is fully data-aware and capable of understanding data models and schemas +* Supports advanced analysis +* Supports automatic discovery and selection of data models based on user prompts. +* Supports quick search and deep research modes +* Supports saving chats and accessing chat history +* Supports third-party MCP connectors + +__Available from 26.2.0.cl and later. To enable Spotter 3 on your instance, contact your ThoughtSpot administrator__. + +**When to use**: + +Use this version if you want to include advanced AI search, research, and analytics capabilities in your ThoughtSpot embedded app. + +|Spotter 2 a|Also known as *Spotter Agent*, it's the second version of Spotter with the following capabilities: + +**Key features and user experience**: + + +* Agentic AI analytics experience +* Context-aware analysis +* Why questions for in-depth analysis +* Coaching in conversations +* Data model instructions and guidance + +__Available when the Spotter 2 experience is enabled on the instance__. + +**When to use**: + +Use this version if you want to include agentic analytics and richer insights in your ThoughtSpot embedded app. + +|Spotter Classic a| An early version of Spotter. + +**Key features and user experience**: + + +* Quick search with queries in natural language format + +* Visualization generation + +__Available if the Spotter Classic version is enabled on the instance__. + +**When to use**: + +You can use this version if your ThoughtSpot embedded app needs only metadata-level insights and does not require or support agentic workflows. +|| +|==== + +== SDK libraries for embedding Spotter +ThoughtSpot provides the following Visual Embed SDK libraries for embedding Spotter capabilities in your app: * xref:embed-spotter.adoc[`SpotterEmbed`] + -To embed the full Spotter interface with a conversation panel that allows natural language queries, data source selection, and interactions with AI-generated Answers, use the `SpotterEmbed` component. -For more information, see xref:embed-spotter.adoc[Embed Spotter]. +Use this SDK component to xref:embed-spotter.adoc[embed the full Spotter experience] in your app. The features in a Spotter embed vary based on the Spotter version. + * xref:embed-spotter-agent.adoc[`SpotterAgentEmbed`] + -The Spotter Agent embedding, also known as `bodyless` embedding, allows you to integrate natural language data search and analysis into your own applications or chatbot. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, the `SpotterAgentEmbed` component is designed for deeper customization, allowing full control over user experience and workflow of embedded analytics. It allows you to build your own UI or agent experience, route user questions to ThoughtSpot, and receive structured answers and visualizations. +Also known as `bodyless` embedding, `SpotterAgentEmbed` allows you to integrate Spotter capabilities into your own applications or chatbot, route user questions to ThoughtSpot, and receive structured answers and visualizations. Unlike the full Spotter experience, the "bodyless" embed includes only a prompt panel with no additional buttons or selectors. + +== Feature status and availability in embed mode + +To link:https://docs.thoughtspot.com/cloud/latest/spotter-enable[enable Spotter experience and AI features, window=_blank] on your instance, contact your ThoughtSpot administrator. + +[width="100%" cols="7,7"] +[options="header"] +|==== +|Feature |Supported version, feature availability, and SDK controls +|https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#_how_to_use_spotter[Spotter search and prompt panel for conversational analytics, window=_blank] + +For quick searches with queries in natural language and for generating visualizations. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag greenBackground tick]#✓# Spotter Classic + +**Feature status**: Generally Available (GA) on all ThoughtSpot Cloud instances. + + +**Required settings**: Spotter feature must be enabled at the instance level. + +**Embed SDK component**: If you want to embed the full Spotter experience, use `SpotterEmbed`. + +To embed only the Spotter search bar with no additional features or standard Spotter user experience, use `SpotterAgentEmbed`. + + +**Default state in embed**: Enabled by default if the ThoughtSpot instance has Spotter experience enabled. + + +|link:https://docs.thoughtspot.com/cloud/latest/spotter-localization[Localization support, window=_blank] + + +Locale settings and language support for Spotter queries and responses. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag greenBackground tick]#✓# Spotter Classic + +**Feature status**: GA. Available on all ThoughtSpot Cloud instances with Spotter feature enabled. + + +**Embed SDK component**: Use `SpotterEmbed`. The SDK also supports configuring locale settings for `SpotterAgentEmbed`. + + +**Required settings**: Locale settings can be configured at the user level in the UI or via REST API. + +**Default state in embed**: By default, the locale settings configured at the instance level will be used. To override the locale settings in your embed, use the xref:locale-setting.adoc#_set_locale_in_the_sdk[locale property in the SDK]. + +|xref:embed-spotter.adoc#_optional_settings_for_spotter_3[New chat interface] + + +The updated chat interface that provides a more intuitive and interactive analytics experience. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Early Access. Available by default on instances that have Spotter 3 enabled. + + +**Required settings**: Spotter 3 must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed`. + + +**Default state in embed**: Disabled by default. To enable this feature, set `updatedSpotterChatPrompt` to `true` in the SDK. + +|Thinking and reasoning UX + + +The thinking and reasoning UX in Spotter conversations shows step-by-step reasoning, planning, and analysis process as Spotter works through a complex question. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + + +**Feature status**: Early Access. Enabled by default on instances with Spotter 2 or Spotter 3 enabled. +**Required settings**: Spotter 2 or Spotter 3 experience must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed`. + + +**Default state in embed**: Enabled by default if the feature is enabled at the instance level. + +|link:https://docs.thoughtspot.com/cloud/latest/spotter-coach-conversation[Spotter coaching within conversation sessions, window=_blank] + +The coaching workflow in Spotter conversations. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + + +**Feature status**: GA in 26.2.0.cl and disabled by default. + +**Embed SDK component**: Use `SpotterEmbed`. + +**Required settings**: Requires Spotter 2 or Spotter 3 experience to be enabled at the instance level. +**Default state in embed**: Enabled by default in 26.2.0.cl and later versions. Developers can use the `Action.InConversationTraining` action ID to control the visibility of this feature in their embeds. + +|link:https://docs.thoughtspot.com/cloud/latest/data-model-instructions[Data model instructions, window=_blank] + + +Global rules that provide data model guidance to the Spotter system and direct how Spotter should interpret queries and construct responses for user prompts. +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + + +**Feature status**: GA. Enabled by default on ThoughtSpot instances with 26.2.0.cl release version or later. + +**Required settings**: Spotter 2 or Spotter 3 experience must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed` + + +**Default state in embed**: Enabled by default. + +|link:https://docs.thoughtspot.com/cloud/latest/spotter-research-mode[Deep Research and analysis mode, window=_blank] + + +Ability to autonomously perform an in-depth and multi-step analysis on a user's question. + + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: GA. Enabled by default on instances with Spotter 3 enabled. + +**Required settings**: Spotter 3 experience must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed` + + +**Default state in embed**: Available by default if Spotter 3 is enabled on the instance. ThoughtSpot embedded app users can select the deep research mode in the Spotter interface. + +|link:https://docs.thoughtspot.com/cloud/latest/spotter-advanced-analysis[Advanced analysis, window=_blank] + + +Ability to function as a data-aware analyst, derive context data model, and perform complex research in Research mode for accurate analysis and deeper insights. Supports forecasting, correlation, and query-on-query analysis. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Early Access. Enabled by default if Spotter 3 is enabled on the instance. + +**Required settings**: Spotter 3 experience must be enabled on the instance. + +**Embed SDK component**: Use `SpotterEmbed`. + + +**Default state in embed**: Available by default if Spotter 3 experience is enabled on the instance. + +|link:https://docs.thoughtspot.com/cloud/latest/spotter-why[Why questions, window=_blank] + +Ability to ask questions to automatically generate explanations and identify key drivers behind changes in a metric using change analysis and AI-generated summaries. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Early Access. Disabled by default. + +**Required settings**: Spotter 2 or Spotter 3 experience must be enabled on the instance. + +**Embed SDK component**: Use `SpotterEmbed` + + +**Default state in embed mode**: Disabled by default. If the feature is enabled on the instance, it will be available in the embed mode. + + +|link:https://docs.thoughtspot.com/cloud/latest/spotter-auto-mode[Auto mode, window=_blank] + +Automatic data source discovery and model selection by Spotter. + +|**Supported Spotter version**: + + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Early Access. Disabled by default. + +**Required settings**: Spotter 3 experience and the *Auto-mode* feature must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed`. + + +**Default state in embed**: Disabled by default. To enable this feature, set the `worksheetId` attribute to `_spotter_data_source_discovery_id` in the SDK. When the Auto mode is enabled, the *Preview data* option in the conversation panel is hidden. + +|link:https://docs.thoughtspot.com/cloud/latest/spotter-conversation-history[Chat history, window=_blank] + + +Saves Spotter conversations and allows reloading chat history with past conversations. -[NOTE] -==== -* The `ConversationEmbed` and `BodylessConversation` components are deprecated and replaced with `SpotterEmbed` and `SpotterAgentEmbed` respectively in Visual Embed SDK v1.38.0 and later. -* If you are embedding the full ThoughtSpot experience in your app via `AppEmbed`, you must set the search bar mode on the home page to `aiAnswer` to view Spotter components. For more information, see xref:full-app-customize.adoc#_include_spotter_interface[Customize full application embedding]. -==== +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic -== Spotter embed and Spotted Agent embed comparison +**Feature status**: Early Access. Enabled by default if Spotter 3 is enabled on the instance. -[width="100%" cols="7,5,5"] -[options='header'] +**Required settings**: Spotter 3 experience and the *Chat history* feature must be enabled at the instance level. + -|===== -| -| Spotter embed -| Spotter Agent embed (Bodyless/Agent) +**Embed SDK component**: Use `SpotterEmbed`. + -|Use case -|Use this method to integrate the built-in AI search and conversation analytics interface in your app. -|Use this method to embed Spotter Search capabilities in your chatbot, virtual agent or an app with your own interface elements and user-experience. +**Default state in embed**: Disabled by default. To enable this feature in the embed mode, set `enablePastConversationsSidebar` to `true` in the SDK. -| Embedding component -| Use `SpotterEmbed` component in the Visual Embed SDK library -| Use `SpotterAgentEmbed` component in the Visual Embed SDK library +|link:https://docs.thoughtspot.com/cloud/latest/spotter-connectors-use[Third-party connectors and MCP tools, window=_blank] + +Third-party tools and services that Spotter can connect to and interact with via Model Context Protocol (MCP). -| Data context -a| * Supported data object is Model + - * Allows data source selection -a| * Supported data object is Model - * Data source is passed in the code. No explicit selection is allowed unless the embedding application UI allows it. +|**Supported Spotter version**: + -| Customization -| The SDK provides several props, object properties, CSS and text customization options for branding and styling, event handlers for host and embed app interaction, and menu action configuration -| The SDK provides limited customization options as the UI/UX controlled by host application. +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic -| Sample Questions -| The SDK provides the ability to show or hide sample questions via `hideSampleQuestions`. -| Not applicable -|===== +**Feature status**: Early Access. Enabled by default if Spotter 3 is enabled on the instance. -== Customization options in the SDK +**Required settings**: Spotter 3 experience and Spotter connectors feature must be enabled on the instance. For connectors to be available in the embed mode, ThoughtSpot administrators must configure Spotter connectors. -Visual Embed SDK provides several configuration settings and controls for customizing Spotter embed view: +**Embed SDK component**: Use `SpotterEmbed`. + -* Configuration properties that enable or disable features. -For more information, see xref:SpotterEmbedViewConfig.adoc[SpotterEmbedViewConfig] and xref:SpotterAgentEmbedViewConfig.adoc[SpotterAgentEmbedConfig] -* The action customization framework to show or hide actions in the embedded view + -For more information, see xref:Action.adoc[Action] and xref:embed-action-ref.adoc[Action IDs in the SDK] -* Event handlers for host and embed app interaction + -For more information, see xref:EmbedEvent.adoc[Embed events], xref:HostEvent.adoc[Host events], and xref:embed-events.adoc[Events and app interactions] -* Style customization framework for customizing styles, text strings, and icons + -See xref:css-customization.adoc[style customization framework] +**Default state in embed**: Visible by default if the `updatedSpotterChatPrompt` attribute is set to `true`. We do not recommend using this feature in your production environment. You can hide this option using the CSS selectors. For more information, see xref:embed-spotter.adoc#_mcp_connectors_and_resource_selection_icon[MCP connectors in Spotter embedding]. +|| +|==== +== Related information -== Additional resources -* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation] -* link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation] +* For more information about Spotter versions and capabilities, see link:https://docs.thoughtspot.com/cloud/latest/spotter[ThoughtSpot Product Documentation, window=_blank]. +* For information about how to embed Spotter and customize the Spotter interface, see xref:embed-spotter.adoc[Embed Spotter] and xref:SpotterEmbedViewConfig.adoc[SpotterEmbedViewConfig]. +* For information about bodyless embedding, see xref:embed-spotter-agent.adoc[Embed Spotter Agent] and xref:SpotterAgentEmbedViewConfig.adoc[SpotterAgentEmbedConfig]. +* For information about the action customization framework to show or hide actions in the embedded view, see xref:Action.adoc[Action] and xref:embed-action-ref.adoc[Action IDs in the SDK]. +* For information about event hooks, see xref:embed-events.adoc[Events and app interactions], xref:EmbedEvent.adoc[Embed events], and xref:HostEvent.adoc[Host events]. +* For information about customization style and CSS variables, see xref:css-customization.adoc[style customization framework]. diff --git a/modules/ROOT/pages/embed-spotter-agent.adoc b/modules/ROOT/pages/embed-spotter-agent.adoc index d8d53c6eb..3dbd95cf8 100644 --- a/modules/ROOT/pages/embed-spotter-agent.adoc +++ b/modules/ROOT/pages/embed-spotter-agent.adoc @@ -18,7 +18,7 @@ Before you begin, check the following: == Import the SDK package -Import the `SpotterEmbed` SDK library to your application environment: +Import the `SpotterAgentEmbed` SDK library to your application environment: **npm** [source,JavaScript] diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index 14cc8120b..746388e69 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -1,23 +1,22 @@ -= Embed Spotter += Embed Spotter experience :toc: true -:toclevels: 3 +:toclevels: 2 :page-title: Embed Spotter :page-pageid: embed-spotter -:page-description: You can use the SpotterEmbed SDK library to embed Conversational analytics experience in your application. +:page-description: You can use the SpotterEmbed SDK library to embed conversational analytics experience in your application. -To embed the full Spotter interface with a conversation panel that allows natural language queries, data source selection, and interactions with AI generated Answers, use the `SpotterEmbed` component. +You can embed the full Spotter experience in your applications using the `SpotterEmbed` component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application. == Before you begin -Before you begin, check the following: +To embed Spotter, you need the following access and setup: -* You have a ThoughtSpot instance with Spotter and Spotter Agent enabled. -* Your host application domain is added to ThoughtSpot CSP and CORS allowlists. -* You have access to the latest version of the Visual Embed SDK or at least v1.33.1. +* Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[required features and settings] on your instance. +* Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists]. +* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK]. == Import the SDK package - Import the `SpotterEmbed` SDK library to your application environment: **npm** @@ -28,6 +27,8 @@ import { AuthType, init, prefetch, + EmbedEvent, + HostEvent } from '@thoughtspot/visual-embed-sdk'; ---- @@ -41,6 +42,8 @@ from '@thoughtspot/visual-embed-sdk'; AuthType, init, prefetch, + EmbedEvent, + HostEvent } from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/index.js'; ---- @@ -50,154 +53,200 @@ from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/index.js'; To initialize the SDK, the following information is required: * `thoughtSpotHost` + -The hostname of your ThoughtSpot application instance. See xref:faqs.adoc#tsHostName[FAQs] to know how to find the hostname of your application instance. +The xref:faqs.adoc#tsHostName[hostname] of your ThoughtSpot application instance. * `authType` + -Authentication type. ThoughtSpot supports a variety of Authentication types. For testing purposes, you can use `AuthType.None`. For other authentication options, see xref:embed-authentication.adoc[Authentication]. +Authentication type. For testing purposes, you can use `AuthType.None`. For information about other authentication options, see xref:embed-authentication.adoc[Authentication]. [source,JavaScript] ---- init({ thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL - authType: AuthType.None, + authType: AuthType.None, // Use the appropriate AuthType for your setup }); ---- == Create an instance of the SpotterEmbed object -Create an instance of the `SpotterEmbed` object and specify the data source ID. Optionally, you can specify the search query string to generate a chart or table at load time. +Create an instance of the `SpotterEmbed` object. + +If you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the *Auto mode* to allow Spotter to automatically discover and select data sources. + +[IMPORTANT] +==== +Auto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== [source,JavaScript] ---- -const conversation = new SpotterEmbed(document.getElementById('ts-embed'), { +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { frameParams: { width: '100%', height: '100%', }, - worksheetId: '<%=datasourceGUID%>', // ID of the data source object to query data - searchOptions: { - searchQuery: 'sales by region', // Optional: initial search query string to pass on load - }, + worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to '_spotter_data_source_discovery_id', + //... other attributes }); ---- -[#configControls] -=== Configuration controls for embed view (Optional) - -The embed package for Spotter includes the additional configuration flags to customize the Spotter interface. -For example, you can hide or disable data source selection using the `hideSourceSelection` and `disableSourceSelection` + -parameters. Disables data source selection panel for embed users when set to `true`. -You can also set locale preference for Spotter interactions using the `locale` property. - -The following code sample sets the locale to English (United Kingdom) and enables viewing Spotter feature limitations. +=== Customize your embed (Optional) +The SDK provides configuration settings to customize the embedded Spotter interface. +For example, you can hide sample questions or disable data source selection using the `hideSampleQuestions` and `disableSourceSelection` parameters. [source,JavaScript] ---- const conversation = new SpotterEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - worksheetId: '<%=datasourceGUID%>', // ID of the data source object to query data - searchOptions: { - searchQuery: 'sales by region', // Optional: initial search query string to pass on load - }, - locale: 'en-GB', - showSpotterLimitations: true, + //...other embed configuration attributes + hideSampleQuestions: true, + disableSourceSelection: true }); ---- +For more information and examples, see xref:embed-spotter.adoc#configControls[Customizing the embedded Spotter interface]. -For a complete list of Spotter embed view configuration settings, see xref:SpotterEmbedViewConfig.adoc[SDK reference Documentation]. +=== Register event listeners -== Customize your embed view -To customize your embedded Spotter views, the following options are available with the Visual Embed SDK: +To listen to the events emitted by the embedded ThoughtSpot component, register xref:embed-events.adoc#embed-events[embed event] handlers. -* Control the xref:embed-spotter.adoc#spotterMenuActions[visibility of menu actions in the embedded view] -* xref:embed-spotter.adoc#_customize_styles_and_interface_elements[Customize styles and interface elements] -* xref:embed-spotter.adoc#_customize_app_interactions_with_events[Customize app interactions] +The following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners. -[#spotterMenuActions] -=== Customize menu actions and elements +[source,JavaScript] +---- +// Register event listeners +spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts +spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded +---- -The SDK provides action IDs to disable, show, or hide the following elements and menu actions via `disabledActions`, `visibleActions`, or `hiddenActions` array. +To trigger actions on the embedded interface, use the xref:HostEvent.adoc[Host events]. -The following menu actions are available by default in the embedded Spotter interface: +The following example shows the host event to reset a Spotter conversation session: -* *Preview data* and *Reset* actions on the conversation panel -* The edit and delete icons on the prompt panel -* *Pin*, *Save*, *Download*, *Modify* on Spotter-generated Answers -* Spotter feedback widget and chart switcher icon on Spotter-generated Answers +[source,JavaScript] +---- +// Example: Add a host event to reset the Spotter conversation +document.getElementById('resetBtn').addEventListener('click', () => { + spotterEmbed.trigger(HostEvent.ResetSpotterConversation); +}); +---- -The following example shows how to disable actions and menu elements using xref:embed-actions.adoc[`disabledActions`] array: +=== Render the embedded object [source,JavaScript] ---- - // Show these actions - visibleActions: [Action.Pin,Action.Save,Action.Edit,Action.PreviewDataSpotter,Action.ResetSpotterChat,Action.SpotterFeedback,Action.EditPreviousPrompt,Action.DeletePreviousPrompt], - // Disable these actions - disabledActions:[Action.PreviewDataSpotter,Action.Edit], - disabledActionReason: "Contact your administrator to enable this feature" +spotterEmbed.render(); ---- -For a complete list of supported actions, see xref:embed-action-ref.adoc#_spotter[Spotter menu actions]. +=== Verify your embed -=== Customize styles and interface elements -To customize the look and feel of the Spotter interface, use the xref:css-customization.adoc[CSS customization framework] in the SDK. The `customizations` object allows you to add xref:customize-css-styles.adoc[custom CSS definitions], xref:customize-text-strings.adoc[text strings], and xref:customize-icons.adoc[icons]. +* Load the embedded object. +** If the embedding is successful, you'll see the Spotter page. +** Initiate a chat session, ask a question, and view the results. +** If you see a blank screen: +*** Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible. +*** Verify whether the authentication credentials used in your code are valid. +* Verify whether the customization settings are applied. -==== Override icons -To override the icons, you must first identify the icon ID, create an SVG file to replace this icon, and add the SVG hosting URL to your embed customization code. +[#configControls] +== Customizing embedded Spotter interface +When you embed Spotter, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding. -The most common icon ID to override is `rd-icon-spotter`, the default Spotter icon. +=== Spotter Classic and Spotter 2 experiences +If you have embedded Spotter Classic or Spotter 2, the initial page includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session. -The following example uses the link:https://github.com/thoughtspot/custom-css-demo/blob/main/alternate-spotter-icon.svg[alternate-spotter-icon.svg, window=_blank] file hosted on `\https://cdn.jsdelivr.net/` to override the Spotter icon. +[.widthAuto] +[.bordered] +image::./images/spotter-embed-legacy.png[Spotter embed] + +=== Spotter 3 experience +In Spotter 3 embedding, you can load the page with a pre-selected data source or use the *Auto mode* to allow Spotter to automatically discover and select a relevant data model for user queries. + +**Default view**: + +[.widthAuto] +[.bordered] +image::./images/spotter3-legacy-interface.png[Spotter 3 interface] + +**With Auto mode enabled**: + +[.widthAuto] +[.bordered] +image::./images/spotter3-leagcy-interface-automode.png[Spotter 3 interface] + +[NOTE] +==== +When Auto mode is enabled, **Preview data** and **Data Model instructions** options will not be available. +==== + +==== Optional settings for Spotter 3 + +Spotter 3 experience is available with a new prompt interface that includes additional features and user elements to enrich your Spotter experience. You can include the *Chat history* panel to allow your users to access the chat history from their previous sessions. + +To enable the new chat interface and chat history features, set the `updatedSpotterChatPrompt` and `enablePastConversationsSidebar` attributes to `true`, as shown in this example: [source,JavaScript] ---- - init({ - //... - customizations: { - // Specify the SVG hosting URL to overide the icon, for example Spotter (`rd-icon-spotter`) icon - iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg" - } - }); +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed configuration attributes + + // Enable the updated Spotter chat prompt experience. + updatedSpotterChatPrompt: true, + + // Enable the sidebar for accessing past Spotter conversations + enablePastConversationsSidebar: true +}); ---- +The following figure shows UI elements and functions available in the new chat prompt and chat history panel: + +[.widthAuto] +[.bordered] +image::./images/spotter3-new-interface.png[Spotter 3 new interface] + +==== MCP connectors and resource selection icon +A connector is an external MCP server or tool, such as Google Drive, Slack, Notion, Confluence, or Jira, which can be used as a data source in Spotter sessions. ThoughtSpot administrators can configure connectors to enable Spotter users to include both structured and unstructured data in their conversation sessions. + +If the new prompt interface in Spotter 3 is enabled, the Spotter page displays the *MCP Connectors* menu along with a '\+' icon in the prompt panel. Your application users can connect to a tool preconfigured by your ThoughtSpot administrator directly from the Spotter 3 prompt interface using the '+' icon and add resources to their conversation context. + [NOTE] ==== -When customizing icons, ensure that the SVG hosting server is added to the CSP allowlist on the *Develop* > *Security Settings* page. For more information, see xref:customize-icons.adoc#_update_allowlists_in_security_settings_page[Customize icons]. +The MCP connector module and the '+' icon are displayed by default if the new prompt interface is enabled in your embed. However, we do not recommend using this feature in your production environments. ==== -==== Customize text strings -To replace text strings, you can use the `stringsIDs` and `strings` properties in the content customization object. - -The following example shows how to replace "Spotter" and other text strings on the Spotter interface. +Currently, the Visual Embed SDK does not provide any attributes or action IDs to hide these elements. As a workaround, you can use the CSS selectors to hide these elements: [source,JavaScript] ---- -// Initialize the SDK with custom text string replacements init({ - // ... - customizations: { - content: { - // Use the strings object to replace the visible UI text with custom labels. - strings: { - // Change all instances of "Liveboard" to "Dashboard" - "Liveboard": "Dashboard", - // Change all instances of "Answer" to "Reports" - "Answer": "Reports", - // Change all instances of "Spotter" to "dataAnlyzer" - "Spotter": "dataAnlyzer", - // Change all instances of "Search" to "Analyze" - "Search": "Analyze", - } + thoughtSpotHost: 'https://your-thoughtspot-host', // URL of your ThoughtSpot instance + authType: AuthType.None, // Authentication type; use appropriate AuthType for your environment + customizations: { + style: { + customCSS: { + rules_UNSTABLE: { + // Hide the MCP connectors module in the Spotter prompt panel + ".button-module__buttonWrapper.chat-connector-resources-module__addConnectorResourceButton": { + "display": "none !important" + }, + // Hide the add resources (+) icon in the Spotter prompt panel + "button.button-module__button.button-module__buttonWithIcon.button-module__tertiary.button-module__sizeM.button-module__backgroundLight.button-module__both": { + "display": "none !important" + } } + } } + }, + // ...other configuration attributes }); ---- +=== Customizing styles and interface elements +The Visual Embed SDK provides a comprehensive style customization framework for overriding icons, text strings, and the appearance of UI elements. + +The `customizations` object allows you to add custom CSS definitions, replace text strings, and override icons. If your customization framework uses external sources or hosting servers, ensure they are added to the CSP allowlist. For more information, see the xref:css-customization.adoc[CSS customization framework], xref:customize-text-strings.adoc[Customize text strings], and xref:customize-icons.adoc[Customize icons] sections. + [#SpotterCSS] -==== Customize styles +=== Customize using CSS variables +You can customize the background color of the conversation and prompt panels, button elements, and the components of the charts generated by Spotter using xref:customize-css-styles.adoc[CSS variables]. -There are several CSS variables available for customizing Spotter interface. You can customize the background color of the conversation and prompt panels, button elements, and the components of the charts generated by Spotter. +If Theme Builder is enabled on your ThoughtSpot instance, you can find the variables for Spotter customization by navigating to *Develop* > *Customizations* > *Theme Builder* in the ThoughtSpot UI and downloading the CSS variables. [source,JavaScript] ---- @@ -219,97 +268,217 @@ init({ }, ---- -For more information about CSS variables for style customization, see xref:customize-css-styles.adoc#_spotter_interface[Spotter interface customization]. +==== Customizing text strings +To replace text strings, you can use the `stringsIDs` and `strings` properties in the content customization object. -== Customize app interactions with events +The following example shows how to replace "Spotter" and other text strings on the Spotter interface. -To listen to the events emitted by the embedded ThoughtSpot component, register xref:embed-events.adoc#embed-events[embed event] handlers. +[source,JavaScript] +---- +// Initialize the SDK with custom text string replacements +init({ + // ... + customizations: { + content: { + // Use the strings object to replace the visible UI text with custom labels. + strings: { + // Change all instances of "Preview data" to "Show data" + "Preview data": "Show data", + // Change all instances of "Spotter" to "dataAnalyzer" + "Spotter": "dataAnalyzer", + } + } + } +}); +---- -The following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners. +=== Customizing the Spotter icon +To override an icon, you must find the ID of the icon, create an SVG file to replace this icon, and add the SVG hosting URL to your embed customization code. The most common icon to override is the default Spotter icon and its icon ID is `rd-icon-spotter`. + +The following example uses the link:https://github.com/thoughtspot/custom-css-demo/blob/main/alternate-spotter-icon.svg[alternate-spotter-icon.svg, window=_blank] file hosted on `\https://cdn.jsdelivr.net/` to override the Spotter icon. [source,JavaScript] ---- - conversation.on(EmbedEvent.Init, showLoader) - conversation.on(EmbedEvent.Load, hideLoader) + init({ + //... + customizations: { + // Specify the SVG hosting URL to override the icon, for example Spotter (`rd-icon-spotter`) icon + iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg" + } + }); ---- -Similarly, to trigger actions on the embedded ThoughtSpot interface, use xref:HostEvent.adoc[Host events]. +The following figures show the customized Spotter icon: +[.widthAuto] +[.bordered] +image::./images/spotter-icon-customization.png[Spotter icon customization] -== Render the embedded object +=== Hiding the Spotter icon and ThoughtSpot branding in the reasoning interface +If you want to hide the Spotter icon from the prompt response page and reasoning interface, or if you want to remove ThoughtSpot branding, you can use the CSS rules with selectors, as shown in this example: [source,JavaScript] ---- -conversation.render(); +init({ + //... embed configuration attributes + customizations: { + style: { + customCSS: { + rules_UNSTABLE: { + // Hide the Spotter icon in the tool call card under reasoning + "svg.chat-module__spotterIcon.icon-module__iconStyle.icon-module__xxl.icon-module__white": { + "display": "none !important" + }, + // Control the visibility for the ThoughtSpot text in the tool call card under reasoning + // Hide the element completely if MCP connectors are enabled, since the text-indent works for ThoughtSpot text only + ".collapsible-item-response-module__title": { + "text-indent": "-89px", + "overflow": "hidden", + "margin-left": "-24px" + }, + // Hide the ThoughtSpot (or Connector) icon in the tool call card under reasoning + ".collapsible-item-response-module__customIconWrapper": { + "display": "none" + }, + }, + }, + }, + } +}); ---- -== Code sample +[#spotterMenuActions] +=== Customizing menu actions and elements + +The SDK provides action IDs to disable, show, or hide the following elements and menu actions via `disabledActions`, `visibleActions`, or `hiddenActions` arrays. + +For example, you can hide the *Preview data*, *Reset* in the prompt panel, or *Pin*, *Download*, and other actions from a Spotter-generated response. + +The following code sample disables actions and menu elements using the xref:embed-actions.adoc[`disabledActions`] array: [source,JavaScript] ---- -import { SpotterEmbed, AuthType, init } from '@thoughtspot/visual-embed-sdk'; + // Hide these actions + hiddenActions: [Action.Pin,Action.ResetSpotterChat,Action.DeletePreviousPrompt], + // Disable actions + disabledActions:[Action.PreviewDataSpotter,Action.Edit], + disabledActionReason: "Contact your administrator to enable this feature" +---- +For a comprehensive list of supported actions, see xref:Action.adoc[Spotter menu actions]. + + +== Code samples -// Initialize the SDK +**Code sample for embedding Spotter Classic and Spotter 2 experience** + +[source,JavaScript] +---- +import { + SpotterEmbed, + AuthType, + init, + EmbedEvent, + HostEvent +} from '@thoughtspot/visual-embed-sdk'; +// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type. init({ - thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL - authType: AuthType.None, // Use the appropriate AuthType for your setup + thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL + authType: AuthType.None, // Use the appropriate AuthType for your setup }); -// Find the container element in your HTML +//Define event handler to show a loading indicator when the embed is initializing. +function showLoader() { + // Show loading indicator +} + +// Define event handler to hide the loading indicator when the embed has loaded. +function hideLoader() { + // Hide loading indicator +} + +// Find the container element in your HTML where the SpotterEmbed will be rendered. const container = document.getElementById('ts-embed'); if (container) { - // Create and render SpotterEmbed - const spotterEmbed = new SpotterEmbed(container, { - frameParams: { - height: '600px', - width: '100%', - }, - worksheetId: 'your-worksheet-id', // ID of the data source object (Model) to query data - searchOptions: { - searchQuery: 'Sales by year', // Optional: initial search query string to populate on load - }, - // Add more configuration options as needed - // Add event listeners as needed - onInit: () => console.log('Spotter initialized'), - onLoad: () => console.log('Spotter loaded'), + // Create and configure the SpotterEmbed + const spotterEmbed = new SpotterEmbed(container, { + frameParams: { + height: '100%', // Set the height of the embedded frame + width: '100%', // Set the width of the embedded frame + }, + worksheetId: 'your-worksheet-id', // ID of the data source object to query data from + //... other configuration attributes }); - spotterEmbed.render(); + // Register event listeners + spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts + spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded + + // Render the SpotterEmbed in the container. + spotterEmbed.render(); + // Example: Add a host event to reset the Spotter conversation + document.getElementById('resetBtn').addEventListener('click', () => { + spotterEmbed.trigger(HostEvent.ResetSpotterConversation); + }); +} ---- -== Test your embed +**Code sample for embedding Spotter 3 experience** -* Build your app and load the embedded object. +[source,JavaScript] +---- +import { + SpotterEmbed, + AuthType, + init, + EmbedEvent, + HostEvent +} from '@thoughtspot/visual-embed-sdk'; +// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type. +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL + authType: AuthType.None, // Use the appropriate AuthType for your setup +}); -** If the embedding is successful, you'll see the Spotter page with a conversation panel. -+ -[.widthAuto] -[.bordered] -image::./images/converseEmbed_default.png[Spotter embed] +//Define event handler to show a loading indicator when the embed is initializing. +function showLoader() { + // Show loading indicator +} -** Add a query, click the prompt button, and view the results. -+ -[.widthAuto] -[.bordered] -image::./images/converseEmbed-with-query.png[Spotter embed] +// Define event handler to hide the loading indicator when the embed has loaded. +function hideLoader() { + // Hide loading indicator +} -** If you see a blank screen: -*** Check if your code has the correct ThoughtSpot host URL. Ensure that your instance is accessible. -*** Check if the authentication credentials in your code are valid +// Find the container element in your HTML where the SpotterEmbed will be rendered. +const container = document.getElementById('ts-embed'); +if (container) { + // Create and configure the SpotterEmbed + const spotterEmbed = new SpotterEmbed(container, { + frameParams: { + height: '100%', // Set the height of the embedded frame + width: '100%', // Set the width of the embedded frame + }, + worksheetId: 'your-worksheet-id', // ID of the data source object to query data from. For automatic model discovery and selection (Auto mode), specify '_spotter_data_source_discovery_id' + updatedSpotterChatPrompt: true, // Enable new chat interface + enablePastConversationsSidebar: true, // Enable chat history + //... other configuration attributes + }); -* Verify the customized objects and elements. + -The following figures show the customized Spotter icon and text: -+ -[.widthAuto] -[.bordered] -image::./images/spotter-icon-customization.png[Spotter icon customization] + // Register event listeners + spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts + spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded -+ -[.widthAuto] -[.bordered] -image::./images/spotter-text-customization.png[Spotter customization] + // Render the SpotterEmbed in the container. + spotterEmbed.render(); + // Example: Add a host event to reset the Spotter conversation + document.getElementById('resetBtn').addEventListener('click', () => { + spotterEmbed.trigger(HostEvent.ResetSpotterConversation); + }); +} +---- == Additional resources -* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation] +* xref:embed-ai-analytics.adoc[Spotter features and embedding options] * link:https://developers.thoughtspot.com/docs/Class_SpotterEmbed[SpotterEmbed classes and methods] * link:https://developers.thoughtspot.com/docs/Interface_SpotterEmbedViewConfig[Configuration options for Spotter interface customization] * link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-embed[Developer examples, window=_blank] +* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Product Documentation] diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index a63084aa0..c13a13eb1 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -27,6 +27,7 @@ The key differences between these UI experience modes are listed in the followin -- [width="100%", cols="2,4,4,5"] [options='header'] + |===== |Feature component |Classic (V1) experience | V2 experience | V3 experience |**UI experience**| Classic layout + diff --git a/modules/ROOT/pages/multi-tenancy-intro.adoc b/modules/ROOT/pages/multi-tenancy-intro.adoc index 47573e469..fa26b8cfb 100644 --- a/modules/ROOT/pages/multi-tenancy-intro.adoc +++ b/modules/ROOT/pages/multi-tenancy-intro.adoc @@ -27,7 +27,7 @@ At a basic level: * if the prod data warehouse is *single-tenanted* and each end customer’s data is separated in different databases or schemas, then a xref:single-tenant-data-models.adoc[prod Org per end customer deployment pattern] is used, with the final deployment from a "release" environment to each individual "end customer prod" environment -The actual level of multi-tenant Org separation is totally up to ThoughtSpot Customer, dependent on your business requirements +The actual level of multi-tenant Org separation is totally up to ThoughtSpot Customer, dependent on your business requirements. //// == Related information diff --git a/modules/ROOT/pages/publish-api.adoc b/modules/ROOT/pages/publish-api.adoc index 323b38239..9d8f65d5d 100644 --- a/modules/ROOT/pages/publish-api.adoc +++ b/modules/ROOT/pages/publish-api.adoc @@ -1,4 +1,4 @@ -= Publish objects to Orgs += Publishing content to Orgs via APIs :toc: true :toclevels: 2 diff --git a/modules/ROOT/pages/publishing-overview.adoc b/modules/ROOT/pages/publishing-overview.adoc index b82b057f2..31899b3e3 100644 --- a/modules/ROOT/pages/publishing-overview.adoc +++ b/modules/ROOT/pages/publishing-overview.adoc @@ -6,7 +6,9 @@ :page-pageid: publish-data-overview :page-description: Use the publishing feature to distrubute and propagete objects to Orgs within a ThoughtSpot instance. -The publishing feature [beta betaBackground]^Beta^ enables administrators to efficiently manage and distribute ThoughtSpot metadata objects across multiple Orgs within a multi-tenant instance. +[earlyAccess eaBackground]#Early Access# + +The publishing feature enables administrators to efficiently manage and distribute ThoughtSpot metadata objects across multiple Orgs within a multi-tenant instance. Unlike the deployment method that relies on TML import and Git integration, publishing allows administrators to create an object in the Primary Org and publish it directly to target Orgs without generating duplicate copies. It also allows dynamic customization of the underlying Table or Connection properties using variables. @@ -14,7 +16,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. +Publishing to Orgs is an Early Access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== == When to use publishing feature @@ -77,8 +79,6 @@ Note the following feature limitations in the beta version: * Only ThoughtSpot administrators with access to all Orgs can publish objects. * Objects can be published only from the Primary Org to other Orgs. * In the target Orgs, published objects are available in read-only mode. The original object in the Primary Org remains editable only by the cluster administrator. -* Spotter functionality is not supported for published objects. -* Search data indexing is disabled for published tables. * Git integration is not supported for published objects. [NOTE] diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index db8adb37c..cf0b4abaf 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -281,6 +281,7 @@ Note the recommendation of Java SDK: [options='header'] |==== |ThoughtSpot release version|Supported SDK version +a|ThoughtSpot Cloud: 26.2.0.cl | v2.21.0 or later a|ThoughtSpot Cloud: 10.15.0.cl | v2.20.0 or later a|ThoughtSpot Cloud: 10.14.0.cl | v2.19.0 or later a|ThoughtSpot Cloud: 10.13.0.cl | v2.18.0 or later diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index ce057f24b..cf9e65de5 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -203,6 +203,7 @@ Note the version recommendations for your ThoughtSpot instances: [options='header'] |==== |ThoughtSpot release version|Recommended SDK version +a|ThoughtSpot Cloud: 26.2.0.cl | v2.21.0 or later a|ThoughtSpot Cloud: 10.15.0.cl | v2.20.0 or later a|ThoughtSpot Cloud: 10.14.0.cl | v2.19.0 or later a|ThoughtSpot Cloud: 10.13.0.cl | v2.18.0 or later diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index ab61008f9..1bb351581 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -896,11 +896,19 @@ ThoughtSpot Software: __9.5.1.sw or later__ a| +++Try it out +++ +a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| +++Try it out +++ a|`POST /api/rest/2.0/system/preferences/communication-channels/search` + Allows searching communication channel preferences. -ThoughtSpot Cloud: __10.14.0.cl or later__ a| +++Try it out +++ +a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/system/security-settings/configure` + +Allows configuring security settings. +a|ThoughtSpot Cloud: __26.2.0.cl or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/system/security-settings/search` + +Allows fetching security settings. +a|ThoughtSpot Cloud: __26.2.0.cl or later__ a| +++Try it out +++ |===== diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index b6e1c54e0..0cce110c0 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,48 @@ 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 26.2.0.cl, February 2026 + +=== Security settings APIs +This release introduces the following Security settings APIs: + +* `POST /api/rest/2.0/system/security-settings/configure` + +Allows configuring security settings at the Org level or for all Orgs on a ThoughtSpot instance. +* `POST /api/rest/2.0/system/security-settings/search` + +Gets a list of security settings configured on specific Org or for all Orgs on a ThoughtSpot instance. + +For more information, see xref:security-settings.adoc[Security Settings]. + +=== Connection API +ThoughtSpot administrators can now revoke OAuth refresh tokens for users who no longer require access to a data warehouse connection via the `/api/rest/2.0/connections/{connection_identifier}/revoke-refresh-tokens` API endpoint. When a token is revoked, the affected user's session for that connection is terminated, and they must re-authenticate to regain access. + +=== Connection configuration API enhancements +You can now include `same_as_parent` and `policy_process_options` attributes in your API request to `/api/rest/2.0/connection-configurations/create` and `/api/rest/2.0/connection-configurations/{configuration_identifier}/update` endpoints. + +The `same_as_parent` parameter specifies if the configuration should inherit settings from its parent. The `policy_process_options` attribute can be used to define additional policy or processing options for the connection, to allow granular control over connection behavior. + +=== Liveboard Report API enhancements +You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. + +For more information, see xref:data-report-v2-api.adoc[Data and Report APIs]. + +=== Email customization API enhancements + +The `template_properties` parameter now has two additional elements for email template customization: + +* `contact_support_url` to add a customized link for contacting customer support. +* `hide_contact_support_url` to hide the option of adding a link for customer support. + +=== System configuration API enhancements +The API response from the `/api/rest/2.0/system/config` endpoint indicates whether SAML or Okta authentication is enabled on the system. + +=== User API enhancements + +* `POST /api/rest/2.0/users/import` + +The `preferred_locale` parameter allows configuring the preferred locale for users being imported via API request. +* `POST /api/rest/2.0/users/search` + +The `include_variable_values` parameter in the API request allows including variable values in the search response. The variable values can be assigned for a user via xref:abac_rls-variables.adoc[ABAC tokens] or xref:variables.adoc#_define_values_and_scope_for_variables[variable API documentation]. + == Version 10.15.0.cl, December 2025 === Spotter APIs diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 050132cc0..24ecca882 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -1,13 +1,14 @@ = Security settings :toc: true -:toclevels: 2 +:toclevels: 3 :page-title: Security settings :page-pageid: security-settings :page-description: Security settings for embedding -The **Security Settings** page in ThoughtSpot UI allows administrators and developers to configure allowlists for Content Security Policy (CSP) and Cross-origin Resource Sharing (CORS), authentication attributes, and access control settings. +ThoughtSpot allows administrators and developers to configure allowlists for Content Security Policy (CSP) and Cross-origin Resource Sharing (CORS), authentication attributes, and access control settings. +These settings can be done via the **Security Settings** page in the ThoughtSpot UI, or through REST APIs v2, by sending a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. == Overview Most web browsers block cross-site scripting, cross-domain requests, and third-party cookies by default. Web browsers also have built-in security mechanisms such as same-origin and content security policies. These policies restrict how applications and scripts from one origin (domain) can interact with the resources hosted on another origin (domain). To ensure data security and a seamless user experience in embedding applications, configure the settings described in this section. @@ -21,9 +22,9 @@ To avoid this issue, ThoughtSpot recommends the following: * If you are using a ThoughtSpot Cloud instance, set up your instance to the same domain as your host application. For more information, see link:https://docs.thoughtspot.com/cloud/latest/custom-domains[Custom domain configuration, window=_blank]. * If you are using authentication methods that rely on cookies, xref:_enable_partition_cookies[enable partition cookies]. -== Security settings in ThoughtSpot +== Configure security settings -Users with administration privileges can configure security settings on the Security settings page of the ThoughtSpot UI. Note that the following settings on the **Security Settings** page will appear as locked for ThoughtSpot Analytics application users and will require an embedding license: +Users with administration privileges can configure security settings on the Security settings page of the ThoughtSpot UI, or by sending a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Note that the following settings on the **Security Settings** page will appear as locked for ThoughtSpot Analytics application users and will require an embedding license: * xref:security-settings.adoc#csp-viz-embed-hosts[CSP visual embed hosts] * xref:security-settings.adoc#cors-hosts[CORS whitelisted domains] @@ -31,22 +32,22 @@ Users with administration privileges can configure security settings on the Secu * xref:configure-saml.adoc#saml-redirect[SAML redirect domains] * xref:trusted-authentication.adoc[Trusted authentication] -=== Security settings for Orgs +==== Security settings for Orgs On ThoughtSpot instances with Orgs, security settings can be managed at two levels: -* Global settings for all Orgs + +* Global settings for all Orgs (cluster level) + Cluster administrators can configure security settings globally for all Orgs. On ThoughtSpot instances with Orgs, the *Develop* page opens in the `Primary Org` context, unless you are accessing the Develop tab from a specific Org context. To configure settings for all Orgs, you must switch to *All Orgs* context. * Org-level settings + -Cluster and Org administrators can configure security settings for a specific Org. Configuration modifications at the Org level do not affect other Orgs or the default settings applied at the All Orgs level. +Cluster and Org administrators can configure security settings for the current logged-in Org. Configuration modifications at the Org level do not affect other Orgs or the default settings applied at the All Orgs level. The following table shows the settings available at the All Orgs and per-Org levels: [width="100%" cols="5,7,7,7"] [options='header'] |===== -||Configuration setting|All Orgs level |Per-Org level +|||All Orgs level (cluster level) |Per-Org level .6+|CSP allowlists | **CSP visual embed hosts** a| [tag greenBackground tick]#Yes# a| [tag redBackground tick]#No# |**CSP connect-src domains** a| [tag greenBackground tick]#Yes# a| @@ -86,11 +87,11 @@ Each Org can have a separate secret key, which can be used to authenticate users ==== -== CSP allowlists +=== CSP allowlists To allow another application to embed ThoughtSpot, you must xref:security-settings.adoc#csp-viz-embed-hosts[add your host application domain as a CSP Visual Embed host]. -To allow xref:security-settings.adoc#csp-connect-src[loading script interfaces and JavaScript events for custom actions], or xref:security-settings.adoc##csp-trusted-domain[to enable importing resources from other sites], add the source domain URLs as trusted hosts in the respective CSP allowlist. +To allow xref:security-settings.adoc#csp-connect-src[loading script interfaces and JavaScript events for custom actions], or xref:security-settings.adoc#csp-trusted-domain[to enable importing resources from other sites], add the source domain URLs as trusted hosts in the respective CSP allowlist. [NOTE] ==== @@ -98,7 +99,7 @@ If your instance has Orgs configured, note that the default Org on your instance ==== [#csp-viz-embed-hosts] -=== Add CSP visual embed hosts +==== Add CSP visual embed hosts To allow your host domain to set the `frame-ancestors` CSP policy header and embed a ThoughtSpot object within your application frame, add your application domain as a CSP visual embed host. . On your ThoughtSpot application instance, go to *Develop* page. @@ -108,13 +109,37 @@ To allow your host domain to set the `frame-ancestors` CSP policy header and emb . In the *CSP visual embed hosts* text box, add the domain names. For valid domain name formats, See xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration]. . Click *Save changes*. + [NOTE] ==== Only users with a valid embed license can add Visual Embed hosts. ==== +*Through the REST API v2* + +Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add your application domain as a CSP visual embed host for your ThoughtSpot application instance by entering valid values for the parameter `visual_embed_hosts`. + +[source,cURL] +---- +curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "cluster_preferences": { + "csp_settings": { + "visual_embed_hosts": [ + "www.thoughtspot.com", + "mysite.com:8080", + "http://localhost:8080" + ] + } + } + }' +---- + + [#csp-connect-src] -=== Add URLs to CSP connect-src allowlist +==== Add URLs to CSP connect-src allowlist If you plan to use a custom action or webhook to send data to an external endpoint or application, you must add the domains of the target endpoints or applications to the `CSP connect-src` allowlist. . On your ThoughtSpot application instance, go to *Develop* page. @@ -124,8 +149,31 @@ If you plan to use a custom action or webhook to send data to an external endpoi . In the *CSP connect-src domains* text box, add the domain names. For valid domain name formats, See xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration]. . Click *Save changes*. + +*Through the REST API v2* + +Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add domains of the target endpoints or applications to the `connect_src_urls` parameter for your ThoughtSpot application instance. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"cluster_preferences": { + "csp_settings": { + "connect_src_urls": [ + "localhost:3000", + "thoughtspot.com" + ] + } +} +}' +---- + [#csp-trusted-domain] -=== Add other trusted domains +==== Add other trusted domains To import images, fonts, and stylesheets from external sites, or load the content from an external site using an iFrame element, you must add the source URLs as trusted domains in the CSP allowlist. For example, in the Liveboard Note tiles, if you want to insert an image from an external site or embed content from an external site in an iFrame, you must add domain URLs of these sites to the CSP allowList. Similarly, to import fonts and custom styles from an external source, you must add the source URL as a trusted domain in ThoughtSpot. @@ -148,7 +196,45 @@ Add the domains from which you want host scripts. For more information, see xref Add the iframe source URL domains. //// -=== Add permitted iFrame domains + +*Through the REST API v2* + +Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add source URLs of sites, where from you can import images, fonts, and stylesheets, as trusted domains to the `img_src_urls`, `font_src_urls`, `style_src_urls`, `script_src_urls` parameters. + +[NOTE] +To be able to add allowed urls for custom JavaScript through `script_src_urls`, `enabled` should be set to `true` for script-src customization. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"cluster_preferences": { + "csp_settings": { + "font_src_urls": [ + "*.thoughtspot.com" + ], + "img_src_urls": [ + "thoughtspot.com/products" + ], + "script_src_urls": { + "enabled": true, + "urls": [ + "thoughtspot:*" + ] + }, + "style_src_urls": [ + "*" + ] + } +} +}' +---- + + +==== Add permitted iFrame domains Features such as link:https://docs.thoughtspot.com/software/latest/liveboard-notes[Liveboard Note tiles, window=_blank] and link:https://docs.thoughtspot.com/cloud/latest/chart-custom[custom charts, window=_blank] allow iFrame content. If you are planning to embed content from an external site, make sure the domain URLs of these sites are added to the iFrame domain allowlist: . On your ThoughtSpot application instance, go to *Develop* page. @@ -159,8 +245,29 @@ Features such as link:https://docs.thoughtspot.com/software/latest/liveboard-not . Click *Save changes*. +*Through the REST API v2* + +Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add domain URLs of external sites using iFrame content are added to the `iframe_src_urls` parameter for your ThoughtSpot application instance. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"cluster_preferences": { + "csp_settings": { + "iframe_src_urls": [ + "www.thoughtspot.com" + ] + } +} +}' +---- + [#cors-hosts] -=== Enable CORS +==== Enable CORS To allow your embedding application to call ThoughtSpot, access its resources, and render embedded content, add your host application domain URL as a trusted host for CORS. @@ -182,8 +289,35 @@ To add domain names to the CORS allowlist, follow these steps: . In the *CORS whitelisted domains* text box, add the domain names. For valid domain name formats, See xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration]. . Click *Save changes*. +*Through the REST API v2* + +Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add CORS allowlist for cross-domain communication to the parameter `cors_whitelisted_urls` for the cluster or for the Org. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ + "org_preferences": [ + { + "cors_whitelisted_urls": [ + "localhost" + ] + } + ], + "cluster_preferences": { + "cors_whitelisted_urls": [ + "mysite.com" + ] + } +}' +---- + + [#csp-cors-hosts] -=== Domain name format for CSP and CORS configuration +==== Domain name format for CSP and CORS configuration [IMPORTANT] ==== @@ -282,10 +416,43 @@ a|+++Wildcard (*) for port+++ |==== -== Block access to non-embedded ThoughtSpot pages +=== Block access to non-embedded ThoughtSpot pages If you have embedded ThoughtSpot content in your app, you may want your users to access only the ThoughtSpot pages embedded within the context of your host app. ThoughtSpot allows administrators to restrict user access to non-embedded application pages from the embedding application context or selectively grant access to specific user groups. For information, see xref:selective-user-access.adoc[Control User Access]. -== Enable partitioned cookies +*Through the REST API v2* + +Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Set `block_full_app_access` to `true` to restrict user access to non-embedded application pages from the embedding application context. Enter values for `groups_identifiers_with_access` to selectively grant access to specific user groups. + +[NOTE] +To be able to gives access through `groups_identifiers_with_access`, the selective user access feature must be turned on in the *Admin settings*. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"cluster_preferences": { + "non_embed_access": { + "block_full_app_access": false + } +}, +"org_preferences": [ + { + "non_embed_access": { + "block_full_app_access": true, + "groups_identifiers_with_access": [ + "group1" + ] + } + } + ] +}' +---- + + +=== Enable partitioned cookies Many web browsers do not allow third-party cookies. If you are using authentication methods that rely on cookies, users will not be able to access the embedded content when browsers block third-party cookies. Therefore, ThoughtSpot recommends using xref:trusted-auth-sdk.adoc[cookieless authentication] in production environments. However, if your implementation uses cookie-based authentication or xref:embed-authentication.adoc#none[AuthType.None], ensure that you enable partitioned cookies: @@ -304,5 +471,40 @@ With partitioned cookies enabled, when a user logs in to ThoughtSpot and accesse Safari blocks all third-party cookies and does not support partitioned cookies. You can switch to a different browser that supports partitioned cookies, or use cookieless authentication in your embedding implementation. ==== -== Trusted authentication +*Through the REST API v2* + +Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Set `enable_partitioned_cookies` to `true` to ensure a cookie is set with the partitioned attribute for applications using cookie-based authentication . + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"cluster_preferences": { + "enable_partitioned_cookies": true +} +}' +---- + +=== Trusted authentication See xref:trusted-authentication.adoc[Trusted authentication] and xref:_secret_key_management[Secret key management]. + +[NOTE] +Trusted authentication is not supported through the REST APIs v2. + +== Retrieve security settings +You can retrieve the security settings for your ThoughtSpot instance by sending a `POST` request to `POST /api/rest/2.0/system/security-settings/search` API endpoint. +You can define the `scope` to get the cluster-level settings (`scope` as `CLUSTER`), or the Org-level settings for the current Org (`scope` as `ORG`). If the `scope` is not specified, the API returns both cluster and Org settings based on user privileges. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/search' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ + "scope": "CLUSTER" +}' +---- diff --git a/modules/ROOT/pages/selective-user-access.adoc b/modules/ROOT/pages/selective-user-access.adoc index 42cccbf41..a6ce63cb8 100644 --- a/modules/ROOT/pages/selective-user-access.adoc +++ b/modules/ROOT/pages/selective-user-access.adoc @@ -75,7 +75,7 @@ If *Block non-embed full app access* is turned on in *All Orgs*, it will be appl For ThoughtSpot releases 10.5.0.cl or earlier, if you have embedded ThoughtSpot using Visual Embed SDK v1.22.0 or later, the `blockNonEmbedFullAppAccess` property in the SDK is set to `true` by default. Due to this, your application users cannot access or navigate to the ThoughtSpot application experience outside the context of your app. -You can turn on the selective user access feature by going to *Admin* > *Early access features* > *Selective User Access* and editing the status to *Enabled*. +You can turn on the selective user access feature by going to *Admin settings* > *Application Settings* > *Administration* > *Selective User Access* and editing the status to *Enabled*. The selective user access granted through the *Security Settings* overrides the `blockNonEmbedFullAppAccess` SDK settings. It is highly recommended that you switch to selective user access for better security and uninterrupted operations. Support for the SDK `blockNonEmbedFullAppAccess` will end soon. diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 84cb5009c..991583d84 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -66,9 +66,9 @@ xref:spotter-apis.adoc#_send_queries_to_a_conversation_session_with_spotter_agen __Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. |Data literacy and guided analysis a| -//* `POST /api/rest/2.0/ai/data-source-suggestions` + -//xref:spotter-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + -//__Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. +* `POST /api/rest/2.0/ai/data-source-suggestions` + +xref:spotter-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + +__Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. * `POST /api/rest/2.0/ai/relevant-questions/`] + xref:spotter-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + @@ -160,43 +160,6 @@ If the API request is successful, a conversation identifier is created. Note the ---- -//// -The following AI API endpoints allow you to initiate a conversation session with Spotter: - -If the API request is successful, the following data is sent in the API response: - -* `session_identifier` + -GUID of the Answer session. -* `generation_number` + -Number assigned to the Answer session. -* `message_type` -Type of response received for the query. For example, `TSAnswer` (ThoughtSpot Answer). -* `visualization_type` + -The data format of the generated Answer; for example, a chart or table. When you download this Answer, the data will be exported in the format indicated by the `visualization_type`. -* `tokens` + -Tokens generated from the natural language search query specified in the API request. These tokens can be used as input to the `/api/rest/2.0/ai/conversation/create` endpoint to set the context for a conversation session. - -[NOTE] -==== -Note the session ID and generation number. To export the result generated from this API call, send these attributes in the `POST` request body to the `/api/rest/2.0/report/answer` endpoint. -==== - -[source,JSON] ----- -[{ - "session_identifier": "57784fa1-10fa-431d-8d82-a1657d627bbe", - "generation_number": 2, - "message_type": "TSAnswer", - "visualization_type": "Undefined", - "tokens": "[product], [region] = [region].'west', sort by [sales] descending" -}] ----- - -== Conversational analytics with Spotter agent -Spotter agent is an advanced, agentic version of Spotter, which supports context-aware interactions, data literacy features, and follow-up conversations for deeper analytics. Spotter agent can be used for complex reasoning and agentic interactions in an orchestrated framework. - -//// - === Send a query to a conversation session To send a question to an ongoing conversation session or ask follow-up questions to , send a `POST` request body with conversation ID and query text to the `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API endpoint. @@ -1036,9 +999,6 @@ Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_sea ==== == Data literacy and query assistance -The query assistance APIs help users who may need assistance with exploring and analyzing data effectively. - -//// The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. === Get data source suggestions @@ -1125,8 +1085,6 @@ The data source ID, name, and description for each recommended data source. * `reasoning` + Reason provided by the LLM to explain why each data source was recommended. -//// - === Get relevant questions The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. diff --git a/modules/ROOT/pages/spottercode-integration.adoc b/modules/ROOT/pages/spottercode-integration.adoc new file mode 100644 index 000000000..bfdf97347 --- /dev/null +++ b/modules/ROOT/pages/spottercode-integration.adoc @@ -0,0 +1,139 @@ += Integrate SpotterCode with your IDE +:toc: true +:toclevels: 2 + +:page-title: SpotterCode integration gude +:page-pageid: integrate-SpotterCode +:page-description: This document provides a comprehensive, step-by-step approach to integrating SpotterCode with your development environment + +Connecting your IDE to ThoughtSpot's SpotterCode is easy. All you need is the SpotterCode MCP Server URL. This guide will walk you through the process of adding SpotterCode to your IDE. + +== Before you begin + +* Ensure that your IDE is AI-native and supports chat sessions with AI models. +* Ensure that you have the necessary permissions to configure MCP servers on your IDE. +* Ensure that the latest version of Node.js is installed in your environment. This is required for building embedding code with the SDK. +* Ensure that you have access to a ThoughtSpot instance and can view the objects and resources that you want to embed or access via the REST API. + +== Integrate SpotterCode with Cursor + +. To add the MCP server URL to your Cursor settings, go to **Cursor Settings** > **Tools and MCP**. Cursor opens the `mcp.json` file. +. Add the SpotterCode MCP Server URL as a remote MCP server. For information about configuring MCP servers in Cursor, refer to the link:https://cursor.com/docs/context/mcp[Cursor Documentation, window=_blank]. ++ +[source,JSON] +---- +{ + "mcpServers": { + "SpotterCode": { + "url": "https://spottercode.thoughtspot.app/mcp" + } + } +} +---- +. Click *Save* and close the `mcp.json` file. This will install the SpotterCode MCP server and tools for the AI models on Cursor to execute. + +== Integrate SpotterCode with Visual Studio Code + +Although you can configure the MCP server in Visual Studio Code, to start a chat session with the AI agent, you'll need GitHub Copilot or a similar extension. + +To add an MCP Server to Visual Studio Code, you can use the Extensions view, the `MCP: Add Server` command via command palette, or directly edit the `mcp.json` file in your workspace configuration. + +[source,JSON] +---- +{ + "servers": { + "SpotterCode": { + "url": "https://spottercode.thoughtspot.app/mcp", + "type": "http" + } + } +} +---- + +After you add the MCP server URL, the SpotterCode MCP server will be available in the Extensions view. For more information about configuring MCP servers in Visual Studio Code, refer to link:https://code.visualstudio.com/docs/copilot/customization/mcp-servers[Visual Studio Code Documentation, window=_blank]. + +== Integrate SpotterCode with Claude Code +To enable SpotterCode in Claude Code, you can add the SpotterCode MCP server URL using the `claude mcp add` command via Claude CLI. If you are using Claude Desktop, you can add the URL directly to the Claude configuration JSON file: + +[source,JSON] +---- +{ + "mcpServers": { + "SpotterCode": { + "url": "https://spottercode.thoughtspot.app/mcp", + } + } +} +---- + +For more information about adding MCP servers to Claude Code, see link:https://code.claude.com/docs/en/mcp[Claude Code Documentation, window=_blank]. + +== Verify the integration + +To verify the integration: + +. Open your application project in your IDE. ++ +If the integration is successful, you'll see SpotterCode in the MCP servers list. + +. Verify the available SpotterCode skills. ++ +For example, Cursor shows the MCP skills of MCP connectors in the **Tools & MCP** page. Check if the xref:spottercode.adoc#_supported_skills[SpotterCode MCP skills] are listed under SpotterCode. As you hover over each skill, you can view the description and input schema used for agentic interactions. You can also disable the MCP skills that you don't want the AI model to use. + ++ +[div videoContainer] +-- +video::./images/cursor_mcp-skills.mp4[width=100%,options="autoplay,loop"] +-- + +. Initiate a chat session and ask a question related to ThoughtSpot embedding, REST APIs, or the SDKs. ++ +In the following example, a chat session with Cursor AI is initiated with the prompt, "I want to embed a ThoughtSpot Liveboard in my React application. Use the available tools to get this information and generate the embed code". Notice how the AI agent uses the SpotterCode skills to get the required information: ++ +[div videoContainer] +-- +video::./images/cursor-chat-session.mp4[width=100%,options="autoplay,loop"] +-- + +. Verify that the AI Agent is able to discover SpotterCode skills and is using these skills to generate a response. +. Review the response returned for your prompt and verify the results. ++ +The following example shows how Cursor AI scaffolds the embed code using the SpotterCode skills. Notice that the AI agent identifies and lists the minimum configuration settings, such as the ThoughtSpot host URL, Liveboard ID, and authentication attributes, required to complete the embedding. + ++ +[div videoContainer] +-- +video::./images/cursor-chat-session2.mp4[width=100%,options="autoplay,loop"] +-- +. When you are prompted to provide additional information, specify these details to continue with the embedding as shown in the following example: + ++ +[div videoContainer] +-- +video::./images/cursor-lb-embed.mp4[width=100%,options="autoplay,loop"] +-- +. Try additional prompts such as adding custom styles, hiding UI menu actions, and more. + +== Additional resources + +* For prompt examples, see xref:spottercode-prompt-guide.adoc#_prompt_examples[Prompt examples and best practices]. +* For troubleshooting tips and workarounds, refer to the xref:spottercode-prompt-guide.adoc#_troubleshooting_errors[Troubleshooting] section. + + +//// +. If your IDE shows the step-by-step explanation of how the Agent how the AI reached its conclusion, you may see the following parameters. These parameters show the input schema of the MCP request to SpotterCode. +* `query` - User's request or question. For example, `how do I embed Liveboard`. +* `version` - Version of the SDK to use. Default is `latest`. +* `topK` - How many relevant documents to return for the query. Default is 5. The agent may increase or decreased the number to get the right answer. +* `symbolName` - Limiting search to a specific item, for example, `LiveboardEmbed`. +* `apiName` - The API node for finding request/response details. +* `additionalDocs` - To include more documentation for extra context, such as Java or TypeScript SDK guidance. + +//// + + + + + + + diff --git a/modules/ROOT/pages/spottercode-prompt-guide.adoc b/modules/ROOT/pages/spottercode-prompt-guide.adoc new file mode 100644 index 000000000..e68e51c06 --- /dev/null +++ b/modules/ROOT/pages/spottercode-prompt-guide.adoc @@ -0,0 +1,158 @@ += SpotterCode prompting guide +:toc: true +:toclevels: 2 + +:page-title: How to use SpotterCode +:page-pageid: spottercode-prompting-guide +:page-description: This document provides best practices, prompt examples and troubleshooting guidance. + +Prompting is an essential step when building embed code for ThoughtSpot integration or when exploring ThoughtSpot REST APIs using SpotterCode. + +This guide provides prompting guidance and best practices to help you get the best results for a variety of use cases. + +== Best practices and recommendations + +* Provide clear, direct, and specific instructions. If you want a code sample as the output and nothing else, specify this in your prompt. +* Avoid multiple task requests in a single prompt. Break down your questions and precisely explain what you want. +* For precise results, use ThoughtSpot terminology, such as Liveboard, Spotter, visualization, and full application embedding. +* To receive specific answers and narrow down your request, mention the SpotterCode skill in instructions. For example, ask `How do I embed a ThoughtSpot page in my app? Use the available SpotterCode tools and skills to get this information`. +* Provide contextual information when asking a question and directing the AI model to perform an action. For example, describe the end goal of the task. If an action must be performed sequentially, use numbered lists or bullet points to ensure the AI agent completes the task as intended. +* Review each response thoroughly. For best results, use the advanced AI models. +* Do not include sensitive or confidential data in prompts. +* Provide additional details and clarifications in the next prompt if you are not getting the desired response. +* Do not rely on SpotterCode to infer business logic that isn’t explicitly defined in the documentation or the SDK. + +== Prompt examples + +For accurate and consistent responses, improve your prompts. + +=== Embedding ThoughtSpot +Refer to the prompt examples in the following table for ThoughtSpot embedding use cases: + +[width="100%" cols="4,4" role="copy-cell-table prompt-guidance-table"] +[options='header'] +|===== +|Vague prompt|Clear prompt +|How do I embed ThoughtSpot?| I want to embed full ThoughtSpot application in my app. Use the available tools to get this information and generate the embed code. +|I want to use ThoughtSpot in my app.| I want to embed a ThoughtSpot Liveboard in my React application. Use the available tools to get this information and generate the embed code. +|Show me how to use the SDK. | I want to embed ThoughtSpot Spotter Search and AI analytics in my application. Use the 'get-visual-embed-sdk-reference' and 'get-developer-docs-reference' tools to get the information and code samples. +|Give me code for embedding analytics. | Provide an example of embedding the full ThoughtSpot application using AppEmbed. +|How do I add Search? | How do I use the SearchEmbed component to embed a search page with a pre-selected data source? +a| +Tell me how to start the SDK in my app. + +Show me how to use the SDK | How do I initialize the ThoughtSpot Visual Embed SDK in a React application? +|What is the embed code for Liveboard? a| Use the SpotterCode tools and generate the embed code for a Liveboard in a React application + +Give me a code sample for embedding a ThoughtSpot Liveboard using the Visual Embed SDK. +|How do I add a chart in my app?| How do I embed a single chart or table from a ThoughtSpot Liveboard in my application? +|How do I use runtime filters? | Show a code example for embedding a Liveboard with two runtime filters: one for 'Region' set to 'Midwest' and one for 'item type' set to 'Jackets', using the Visual Embed SDK. +|Add an event hook to Liveboard. | Generate a React component that uses the ThoughtSpot embed SDK to display a Liveboard and add an event to trigger filter updates. +|Can I customize the embed?| Fetch the documentation for the LiveboardEmbed class and summarize the available customization options. +a|How do I update my code? + + +Update to new version +|Update my embed code using the latest Visual Embed SDK version and highlight any breaking changes from the documentation. +a| Show me an example with filters + + +Add filters to my embed +a| +* List all supported runtime filter operators and provide code examples for each using the SDK. +* Show how to apply an OR condition in runtime filters for product names containing 'bag' or 'jackets' in the embed code. +* Explain how to embed a Liveboard with a date filter using epoch time format, and show a code sample. +|Give me code for embedding analytics | Provide a code snippet to embed Spotter and pass a search query string as a prop +a| Change the Liveboard layout + +Make my embed dynamic +a| Show how to customize the Liveboard breakpoint width and explain the impact. + +Show me how to customize the layout of charts in the embedded Liveboard. +|Add custom styles to buttons| Change the background color of the Call To Action (CTA) buttons in the embed view to Cerulean blue (#2A52BE). +|===== + +=== ThoughtSpot REST APIs + +If using ThoughtSpot REST APIs in application workflows, consider using the examples listed in the following table: + +[width="100%" cols="4,4" role="copy-cell-table prompt-guidance-table"] +[options='header'] +|===== +|Vague prompt|Clear prompt +|How do I get the dashboards via API| How do I get a list of my Liveboards via ThoughtSpot REST API? +a| Show me how to connect to the API + + +Show me how to use the API a| +Show a cURL example for authenticating to ThoughtSpot REST API v2.0 using OAuth + + +Generate a POST request to /api/rest/2.0/metadata/search, including required headers and body. +|How do I add a user using API? a| +How do I create a new user with admin privileges via REST API? Provide the endpoint, method, and sample payload. +|Get data from a chart via API| Generate a REST API request example to fetch data from a specific chart in a Liveboard. +|What do I need to include in my API request? | What headers are required for a REST API call to ThoughtSpot? List and explain each. +|How do I see new actions in my app? | How do get a list of custom actions added in my embed via REST API? +|===== + +== Troubleshooting errors +This section lists the common error scenarios, root causes, and recommended actions for troubleshooting errors related to SpotterCode integration. If the error persists, contact ThoughtSpot Support for further assistance. + +=== SpotterCode is not responding or failing to load + +Possible causes:: +- SpotterCode is not installed or enabled. +- Incorrect MCP Server URL or errors in the MCP configuration file. +- SpotterCode server is not reachable. + +Recommended actions:: +- Ensure the SpotterCode is properly installed and enabled in your IDE. +- Verify whether the SpotterCode MCP server is reachable. If the server is not reachable, contact ThoughtSpot Support. +- Verify whether your organization's network/firewall settings are blocking communication. +- Exit and restart your application and try connecting again. + +=== Unable to start a chat with SpotterCode + +Possible causes:: +- Development environment non-AI-native or not AI-enabled. + +Recommended actions:: +- If your IDE is not AI-native, try installing an extension, such as Copilot. +- Check if your environment has access to AI models. +- Start a chat session and specify the Agent to use SpotterCode skills. If the issue persists, contact your application administrator. + +=== Slow response time + +Possible causes:: + +- The prompt is complex, involves multiple actions, or includes a broader context, resulting in a longer search and processing time. +- High server load or network latency can further delay the response. + +Recommended actions:: +- Make your prompt as specific as possible. Specify the SDK version, the exact component, and the desired output. For best results, break down complex requests into smaller, sequential prompts. Refer to xref:spottercode-prompt-guide.adoc#_prompt_examples[prompt examples] and xref:spottercode-prompt-guide.adoc#_best_practices_and_recommendations[best practices] for tips. +- Try using a different AI model and review. +- Reset the chat session and try it again. + +=== Incorrect or irrelevant response + +Possible causes:: +- The AI Agent is not using the right skills or the input schema of the MCP skills efficiently. +- The prompt input is complex or ambiguous. + +Recommended actions:: +- Check the response generation flow to see the query parameters used by the AI Agent in its MCP request. +- Refine your query to be more specific. Refer to the best practices and Prompt examples recommended by ThoughtSpot. +- Choose a different AI model and review the results. + +=== Errors in code samples due to version mismatch + +Possible causes:: +- SpotterCode used a different version for code generation. +- No version was specified in the prompt. + +Recommended actions:: +- SpotterCode uses the latest version of the SDK by default. If you'd like to use a different version, specify the version in your prompt. +- Review API and SDK changelog in the documentation for feature deprecation and breaking changes. + +=== SDK client context mismatch + +Possible causes:: +SpotterCode couldn't determine the SDK content for your application or client. + +Recommended actions:: +Although the AI Agent on your IDE is capable of finding relevant information for your project context, we recommend stating the client environment and required SDK client library clearly in the prompt. + diff --git a/modules/ROOT/pages/spottercode.adoc b/modules/ROOT/pages/spottercode.adoc new file mode 100644 index 000000000..b37ed7906 --- /dev/null +++ b/modules/ROOT/pages/spottercode.adoc @@ -0,0 +1,94 @@ += SpotterCode +:toc: true +:toclevels: 2 + +:page-title: SpotterCode +:page-pageid: SpotterCode +:page-description: Use SpotterCode to accelerate code generation and the process of embedding and integrating ThoughtSpot. + +ThoughtSpot’s SpotterCode is an AI-powered MCP tool that streamlines and speeds up the process of embedding ThoughtSpot content and integrating ThoughtSpot REST APIs in your application workflows. + +== What is SpotterCode? +SpotterCode connects your integrated development environment (IDE) to a ThoughtSpot-hosted MCP server. It empowers AI-native IDEs with tools and documentation lookup capabilities, providing direct access to ThoughtSpot SDKs, REST API documentation, code samples, and developer guides. The AI agents in the IDE can use these skills to assist developers in embedding ThoughtSpot content and integrating REST API workflows into their applications. + +[IMPORTANT] +==== +SpotterCode is an add-on tool available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. If you have a ThoughtSpot Analytics license with an active ThoughtSpot Embedded subscription, you can integrate SpotterCode using the SpotterCode MCP Server URL in your coding application. +==== + +== Who should use SpotterCode? +SpotterCode is intended for developers and technical teams integrating ThoughtSpot content and workflows into their applications using Visual Embed SDK and REST APIs, with a particular focus on those working in AI-native IDEs such as Cursor. + +When integrated, SpotterCode offers the following advantages: + +* Empowers your IDE with the documentation lookup and provides direct access to authoritative information on embedding ThoughtSpot or integrating REST API workflows in your development projects. + +* Accelerates the process of embedding and integration by providing code samples, SDK skills, and custom styling directly in the IDE. + +* Enables developers to build context-aware and deployment-ready code tailored to their project structure, thereby reducing manual effort and errors. + +* Reduces operational strain by rapidly generating boilerplate code required for embedding ThoughtSpot in your application. + +[NOTE] +==== +SpotterCode is an acceleration tool designed to help developers streamline the process of integrating ThoughtSpot into their projects. It does not replace the Visual Embed SDK or the foundational knowledge required for embedding or application integration. +==== + +== Supported IDEs + +The initial version of SpotterCode supports the following IDEs: + +* Cursor AI +* Visual Studio Code with GitHub Copilot +* Claude Code + +== Supported skills +SpotterCode provides the following skills to the AI agent on your IDE: + +* `get-visual-embed-sdk-reference` + +A documentation lookup skill that accesses Visual Embed SDK documentation and generates code samples for embedding ThoughtSpot content, including supported embed types, authentication, configuration, customization, event hooks, and code samples. + +* `get-rest-api-reference` + +Provides REST API specifications, endpoints, request/response formats, authentication flows, CRUD operations, and SDKs for TypeScript and Java. + +* `get-developer-docs-reference` + +Provides access to documentation on embedding, UI customization, deployment, security, and best practices. + +== Limitations + +- Responses from SpotterCode are determined by the features and parameters currently supported in the Visual Embed SDK, REST API, and official ThoughtSpot Developer documentation. SpotterCode cannot generate code or solutions that rely on unsupported or undocumented features. +- SpotterCode can generate code samples for the most common use cases. Scenarios that require advanced customization or highly specialized workflows may require manual intervention or additional coding beyond what SpotterCode provides. +- SpotterCode does not influence how the Spotter feature in your ThoughtSpot embed infers semantic modeling. SpotterCode is not intended for querying data models or interpreting definitions such as measures and attributes in your metadata objects. +- The behavior of the IDE agent, including tool selection and reasoning, is not controlled by SpotterCode. + +== Next steps + +++++ +
+
+
+
Integrate SpotterCode with your IDE
+ +

+Connect your development environment to SpotterCode and use SpotterCode skills.

+

+
+ +
+ +
+
+
View prompt examples and best practices
+

+Learn how to use SpotterCode in your IDE for best results and explore example prompts.

+

+
+ +
+ +
+ +++++ + + + diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc index 0cd67412f..dafd73e9c 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -35,7 +35,6 @@ Formula variables can be set for an Org, user, or Model and can be used in RLS r The Variable API allows administrators to define formula variables for the `VARCHAR`, `BIGINT`, `INT`, `FLOAT`, `DOUBLE`, `BOOLEAN`, `DATE`, `DATE_TIME`, and `TIME` data types. - === APIs for Variable creation and management The following REST API endpoints are available for variable creation and management: @@ -51,10 +50,12 @@ xref:variables.adoc#_get_details_of_variables[Retrieves the variables available xref:variables.adoc#_delete_a_variable[Deletes the variable] specified in the API request. +//// [NOTE] ==== Variable operations through the REST API are in beta. To enable this feature on your instance, contact ThoughtSpot Support. ==== +//// == Before you begin diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index d7955f3a7..c59a7b19b 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -10,7 +10,38 @@ This page lists new features, enhancements, and deprecated functionality in Thou == Version 26.2.0.cl -The ThoughtSpot Cloud 26.2.0.cl version is now available for ThoughtSpot Embedded instances. For information about the new features and enhancements introduced in this release, see link:https://developers.thoughtspot.com/docs/26.2.0.cl?pageid=whats-new[26.2.0.cl Developer Documentation, window=_blank]. +=== SpotterCode extension for IDEs [earlyAccess eaBackground]#Early Access# + +ThoughtSpot introduces SpotterCode, an AI-powered Model Context Protocol (MCP) extension for Integrated Development Environments (IDEs) such as Cursor, Visual Studio Code, and Claude Code. When integrated, SpotterCode enables the AI agent in the IDE to access ThoughtSpot SDKs and API documentation resources, and provide in-context coding assistance to developers embedding ThoughtSpot content within their applications. + +SpotterCode is available as an Early Access feature and can be integrated with development environments that support MCP servers and tools. For more information, see xref:spottercode.adoc[SpotterCode], xref:spottercode-integration.adoc[Integrating SpotterCode in IDEs], and xref:spottercode-prompt-guide.adoc[SpotterCode prompting guide]. + +=== Spotter 3 experience [earlyAccess eaBackground]#Early Access# +You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. + +For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Spotter embedding documentation]. + +=== Rate limits for REST APIs +To prevent excessive requests from reaching application servers and ensure API stability and service quality for REST API users, ThoughtSpot enforces rate limits on public API requests per client IP. These limits are applied globally at the cluster level for all public API requests, including calls to both REST API v1 and v2 endpoints. +//Administrators can adjust these limits for their ThoughtSpot deployments as needed. + +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. + +=== Security settings via REST APIs +The security settings for ensuring data security and a seamless embedded user experience can now be done through REST APIs v2. Administrators and developers can configure allowlists for: + +* Content Security Policy (CSP) +* Cross-origin Resource Sharing (CORS) +* Authentication attributes +* Access control settings + +For more information, see xref:security-settings.adoc[Security Settings]. + +=== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.45.0, see the xref:api-changelog.adoc[Visual Embed changelog]. + +=== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. == Version 10.15.0.cl diff --git a/src/components/Document/helper.tsx b/src/components/Document/helper.tsx index 1e5050a85..a1351b3fc 100644 --- a/src/components/Document/helper.tsx +++ b/src/components/Document/helper.tsx @@ -51,6 +51,44 @@ export const customizeDocContent = () => { wrapperDiv.appendChild(buttonElement); tag.parentElement.appendChild(wrapperDiv); }); + /* Add copy buttons to marked table cells */ + document + .querySelectorAll('.copy-cell-table table, table.copy-cell-table') + .forEach((table) => { + (table as HTMLElement) + .querySelectorAll('tbody tr td:nth-child(2)') + .forEach((cell) => { + const cellElement = cell as HTMLElement; + if (cellElement.querySelector('.tableCopyButton')) { + return; + } + cellElement.classList.add('tableCopyCell'); + const contentWrapper = document.createElement('div'); + contentWrapper.classList.add('tableCopyContent'); + while (cellElement.firstChild) { + contentWrapper.appendChild(cellElement.firstChild); + } + cellElement.appendChild(contentWrapper); + const buttonElement = document.createElement('button'); + buttonElement.setAttribute('class', 'tableCopyButton'); + buttonElement.setAttribute( + 'aria-label', + t('CODE_COPY_BTN_HOVER_TEXT'), + ); + buttonElement.setAttribute( + 'title', + t('CODE_COPY_BTN_HOVER_TEXT'), + ); + enableCopyToClipboard(buttonElement, contentWrapper); + const imageElement = document.createElement('span'); + imageElement.innerHTML = getHTMLFromComponent( + , + 'copyIcon', + ); + buttonElement.appendChild(imageElement); + cellElement.appendChild(buttonElement); + }); + }); /* To highlight code snippets */ document.querySelectorAll('pre code').forEach((block) => { hljs.highlightBlock(block as HTMLElement); diff --git a/src/components/Document/index.scss b/src/components/Document/index.scss index 06623644c..ff4d74ec1 100644 --- a/src/components/Document/index.scss +++ b/src/components/Document/index.scss @@ -165,6 +165,7 @@ background-color: var(--table-header-color); position: sticky; top: 0; + z-index: 2; } td { @@ -179,6 +180,34 @@ margin: 3px 0; } } + .tableCopyCell { + position: relative; + padding-right: calc(#{$padding-md} + 54px); + + .tableCopyButton { + position: absolute; + top: 6px; + right: 6px; + border: 0; + background: transparent; + padding: 2px; + opacity: 0; + visibility: hidden; + cursor: pointer; + display: inline-flex; + align-items: center; + gap: 4px; + font-size: 12px; + color: var(--secondary-color); + } + + &:hover .tableCopyButton, + .tableCopyButton:focus, + .tableCopyButton:focus-visible { + opacity: 1; + visibility: visible; + } + } tr { border-bottom: 1px solid var(--border-color-tr); @@ -191,6 +220,24 @@ } } + .prompt-guidance-table table td, + table.prompt-guidance-table td { + padding-right: $padding-xs; + } + + .prompt-guidance-table table td.tableCopyCell, + table.prompt-guidance-table td.tableCopyCell { + padding-right: calc(#{$padding-xs} + 52px); + } + + .prompt-guidance-table table .tableCopyCell .tooltiptext, + table.prompt-guidance-table .tableCopyCell .tooltiptext { + color: #2770ef; + font-size: $font-size-table; + font-family: $font-family-doc; + font-weight: $font-weight-normal; + } + h2 { diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 96855667b..beb229d2e 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -48,9 +48,16 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '10.15.0.cl', + label: '26.2.0.cl', link: ' ', subLabel: 'Cloud (Latest)', + iframeUrl: 'https://developer-docs-26-2-0-cl.vercel.app/docs/', + }, + { + label: '10.15.0.cl', + link: '10.15.0.cl', + subLabel: 'Cloud', + iframeUrl: 'https://developer-docs-10-15-0-cl.vercel.app/docs/', }, { label: '10.14.0.cl', @@ -76,12 +83,6 @@ module.exports = { subLabel: 'Software', iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', }, - { - label: '26.2.0.cl', - link: '26.2.0.cl', - subLabel: 'Coming soon', - iframeUrl: 'https://developer-docs-26-2-0-cl.vercel.app/docs/', - }, ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', diff --git a/static/doc-images/images/cursor-chat-response.mp4 b/static/doc-images/images/cursor-chat-response.mp4 new file mode 100644 index 000000000..dcfe07340 Binary files /dev/null and b/static/doc-images/images/cursor-chat-response.mp4 differ diff --git a/static/doc-images/images/cursor-chat-session.mp4 b/static/doc-images/images/cursor-chat-session.mp4 new file mode 100644 index 000000000..89224a63b Binary files /dev/null and b/static/doc-images/images/cursor-chat-session.mp4 differ diff --git a/static/doc-images/images/cursor-chat-session2.mp4 b/static/doc-images/images/cursor-chat-session2.mp4 new file mode 100644 index 000000000..059fd226b Binary files /dev/null and b/static/doc-images/images/cursor-chat-session2.mp4 differ diff --git a/static/doc-images/images/cursor-chat.mp4 b/static/doc-images/images/cursor-chat.mp4 new file mode 100644 index 000000000..059fd226b Binary files /dev/null and b/static/doc-images/images/cursor-chat.mp4 differ diff --git a/static/doc-images/images/cursor-lb-embed.mp4 b/static/doc-images/images/cursor-lb-embed.mp4 new file mode 100644 index 000000000..3ff19ae31 Binary files /dev/null and b/static/doc-images/images/cursor-lb-embed.mp4 differ diff --git a/static/doc-images/images/cursor_mcp-skills.mp4 b/static/doc-images/images/cursor_mcp-skills.mp4 new file mode 100644 index 000000000..a79d95c9b Binary files /dev/null and b/static/doc-images/images/cursor_mcp-skills.mp4 differ diff --git a/static/doc-images/images/mcp-skills.png b/static/doc-images/images/mcp-skills.png new file mode 100644 index 000000000..e9dabc46c Binary files /dev/null and b/static/doc-images/images/mcp-skills.png differ diff --git a/static/doc-images/images/spotter-embed-legacy.png b/static/doc-images/images/spotter-embed-legacy.png new file mode 100644 index 000000000..45fe13945 Binary files /dev/null and b/static/doc-images/images/spotter-embed-legacy.png differ diff --git a/static/doc-images/images/spotter3-leagcy-interface-automode.png b/static/doc-images/images/spotter3-leagcy-interface-automode.png new file mode 100644 index 000000000..3e05cf10b Binary files /dev/null and b/static/doc-images/images/spotter3-leagcy-interface-automode.png differ diff --git a/static/doc-images/images/spotter3-legacy-interface.png b/static/doc-images/images/spotter3-legacy-interface.png new file mode 100644 index 000000000..581f1aaeb Binary files /dev/null and b/static/doc-images/images/spotter3-legacy-interface.png differ diff --git a/static/doc-images/images/spotter3-new-interface.png b/static/doc-images/images/spotter3-new-interface.png new file mode 100644 index 000000000..cd9b1676b Binary files /dev/null and b/static/doc-images/images/spotter3-new-interface.png differ diff --git a/static/doc-images/images/spotter3-new-interface_auto-mode.png b/static/doc-images/images/spotter3-new-interface_auto-mode.png new file mode 100644 index 000000000..b8ce7a452 Binary files /dev/null and b/static/doc-images/images/spotter3-new-interface_auto-mode.png differ diff --git a/static/doc-images/images/spottercode-embed.png b/static/doc-images/images/spottercode-embed.png new file mode 100644 index 000000000..746765437 Binary files /dev/null and b/static/doc-images/images/spottercode-embed.png differ diff --git a/static/doc-images/images/spottercode-prompt-response.png b/static/doc-images/images/spottercode-prompt-response.png new file mode 100644 index 000000000..ef7fab6a8 Binary files /dev/null and b/static/doc-images/images/spottercode-prompt-response.png differ diff --git a/static/doc-images/images/spottercode-response-2.png b/static/doc-images/images/spottercode-response-2.png new file mode 100644 index 000000000..925061ce0 Binary files /dev/null and b/static/doc-images/images/spottercode-response-2.png differ diff --git a/static/doc-images/images/spottercode-response.png b/static/doc-images/images/spottercode-response.png new file mode 100644 index 000000000..205a7da7e Binary files /dev/null and b/static/doc-images/images/spottercode-response.png differ diff --git a/static/doc-images/images/spottercode-response3.png b/static/doc-images/images/spottercode-response3.png new file mode 100644 index 000000000..f9ffc704a Binary files /dev/null and b/static/doc-images/images/spottercode-response3.png differ diff --git a/static/doc-images/images/spottercode-response4.png b/static/doc-images/images/spottercode-response4.png new file mode 100644 index 000000000..6c34fca98 Binary files /dev/null and b/static/doc-images/images/spottercode-response4.png differ diff --git a/static/doc-images/images/spottercode-skill-selection.png b/static/doc-images/images/spottercode-skill-selection.png new file mode 100644 index 000000000..c16a1d8f2 Binary files /dev/null and b/static/doc-images/images/spottercode-skill-selection.png differ