From bdf8ad4b8bb89b9494165c8b4bca98e59153e9a1 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:14:05 +0530 Subject: [PATCH 01/63] =?UTF-8?q?docs(26.8.0.cl):=20Add=20August=202026=20?= =?UTF-8?q?What's=20New=20entries=20=E2=80=94=20Spotter=20Analysts,=20Spot?= =?UTF-8?q?terViz=20Insight=20Tiles,=20Nav=20V1/V2=20deprecation,=20TSE=20?= =?UTF-8?q?GA=20features,=20WYSIWYG=20PDF,=20split=20download=20privilege,?= =?UTF-8?q?=20TML=20portability,=20Collections=20obj=5Fid,=20Discoverabili?= =?UTF-8?q?ty=20removal,=20Schedule=20deprecation,=20Business=20Terms=20de?= =?UTF-8?q?precation,=20Spotter=20Model=20GA=20[SCAL-295712,=20SCAL-309481?= =?UTF-8?q?,=20SCAL-273333,=20SCAL-312731,=20SCAL-292918,=20SCAL-310399,?= =?UTF-8?q?=20SCAL-312622,=20SCAL-309017,=20SCAL-307283,=20SCAL-317357,=20?= =?UTF-8?q?SCAL-306340,=20SCAL-313088,=20SCAL-293483,=20SCAL-244749]"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/whats-new.adoc | 638 +++++++++--------------------- 1 file changed, 183 insertions(+), 455 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index dc99edbb4..e997d3ecf 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -23,631 +23,359 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Affects:* Developers, Administrators, End Users // ============================================================ -== July 2026 - -**Release version**: ThoughtSpot Cloud 26.7.0.cl + -*Upgrade notes*: No breaking changes + -*Recommended SDK versions*: Visual Embed SDK v1.50.0 and later - -[.cl-table, cols="2,4", frame=none, grid=none] -|===== -a| -[.cl-label] -*Version 26.7.0.cl* - -a| -[discrete] -==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# -You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. - -For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. - ---- - -[discrete] -==== Spotter embedding - -Spotter file upload in embedded apps:: -Applications embedding the Spotter interface can now allow their users to xref:embed-spotter.adoc#_enable_file_upload_in_spotter_chat[upload files directly in the Spotter chat panel]. - -Spotter conversation history:: -You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. - -Spotter Agent instructions:: -You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. - ---- - -[discrete] -==== Focused home page experience [earlyAccess eaBackground]#Early Access# - -In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. - ---- - -[discrete] -==== Webhooks enhancements - -ThoughtSpot introduces the following features and enhancements for webhook configuration and management: - -* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + -The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. -* Storage configuration retrieval + -The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. -* GCS storage configuration for webhook delivery + -Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. -* Webhook activation and deactivation + -You can enable or disable a webhook connection in the UI or through REST API. -* Selective configuration reset + -The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. - ---- - -[discrete] -==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# - -The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically, accelerates building code and iterating embed configurations. - -For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. - ---- - -[discrete] -==== Org isolation for per-org SAML and OIDC authentication -ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. - ---- - -[discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. - ---- - -[discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +// ============================================================ +// SOURCE: SCAL-295712, SCAL-309481, SCAL-273333, SCAL-312731, SCAL-292918, +// SCAL-310399, SCAL-312622, SCAL-309017, SCAL-307283, SCAL-317357, +// SCAL-306340, SCAL-313088, SCAL-273513, SCAL-298371, SCAL-293483, +// SCAL-244749, SCAL-323283, SCAL-303476 +// TODO: [WRITER] Confirm the exact calendar month label ("August 2026") with +// the release team before publishing. SCAL-295712 targets 26.8.0.cl but +// the calendar ship date is not confirmed at time of authoring (2026-07-10). +// ============================================================ ---- +== August 2026 -|===== - -== June 2026 - -**Release version**: ThoughtSpot Cloud 26.6.0.cl + -*Upgrade notes*: No breaking changes. + -*Recommended SDK versions*: Visual Embed SDK v1.49.0 and later +**Release version**: ThoughtSpot Cloud 26.8.0.cl + +*Upgrade notes*: See individual feature entries below for backward-compatibility notes. The Navigation V1/V2 deprecation may require SDK configuration updates. + +*Recommended SDK versions*: Visual Embed SDK v1.51.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |===== a| [.cl-label] -*Version 26.6.0.cl* +*Version 26.8.0.cl* a| [discrete] -==== Chart and table overrides [.version-badge.new]#New# -You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: +==== Spotter Analysts [earlyAccess eaBackground]#Early Access# +// SOURCE: SCAL-310399, SCAL-312622 +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl +// TODO: [WRITER] Confirm EA vs GA status with Agents Experience team (Karamveer Singh) before publishing. +// TODO: [WRITER] Confirm the full list of Action enum values for Analyst actions in types.ts once SDK 1.51.0 is tagged — verify Action.ShowAnalysts, Action.CreateAnalyst, Action.EditAnalyst, Action.MakeCopyAnalyst, Action.ShareAnalyst, Action.DeleteAnalyst exist in the released SDK. +Spotter now includes an *Analysts* panel in the sidebar that surfaces dedicated Spotter Analyst agents. Each Analyst is scoped to a specific data model and skill set, enabling your embedded users to start focused AI-driven conversations without manually selecting a data source. -* Chart overrides + -Control legend visibility and position, data label display and per-column filter -thresholds, regression lines, grid lines, axis range and label settings, series -colors, and conditional formatting rules including font and background styling. -* Table overrides + -Control column visibility, text wrapping, row height and padding density, table -theme, and column summary visibility with per-column exceptions. +In ThoughtSpot Embedded, the Analysts section is disabled by default. The Visual Embed SDK 1.51.0 introduces the following controls: -For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. +Custom labels (in `SpotterSidebarViewConfig`)::: +* `spotterAnalystLabel` — Custom singular label for the Analyst entity. Default: `Analyst`. +* `spotterAnalystsLabel` — Custom label for the Analysts sidebar section. Default: `Analysts`. ---- - -[discrete] -==== Spotter AI and embedding enhancements [.version-badge.new]#New# +Starter prompts (in `SpotterChatViewConfig`)::: +* `enableStarterPrompts` — When set to `true`, shows onboarding starter prompts on initial load. Default: `false`. -This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. +Action IDs for `hideActions` or `disableActions`::: +* `Action.ShowAnalysts`, `Action.CreateAnalyst`, `Action.EditAnalyst`, `Action.MakeCopyAnalyst`, `Action.ShareAnalyst`, `Action.DeleteAnalyst` -* Spotter embedding: + -Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. -* Spotter AI APIs: + -//** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. - New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. +For more information, see xref:embed-spotter.adoc#spotter-analysts[Spotter Analysts in embedded applications]. --- [discrete] -==== Developer page enhancements -The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: - -* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. -* Removal of REST API v1 + -The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. -* Removal of GraphQL playgrounds + -The menu link to the GraphQL playground has been removed from the UI. +==== SpotterViz Insight Tiles [earlyAccess eaBackground]#Early Access# +// SOURCE: SCAL-309017 +// SOURCE: src/embed/spotter-viz-utils.ts @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl +// TODO: [WRITER] Confirm the exact embed config properties for Insight Tiles with the SpotterViz team. The loaderHeadline/loaderTips properties are confirmed from SDK source; confirm whether additional Insight Tile-specific config exists. +// TODO: [WRITER] Add a screenshot of SpotterViz Insight Tiles in the Liveboard Agent panel once available from the design team. +ThoughtSpot introduces *Insight Tiles* in the SpotterViz experience on embedded Liveboards. Insight Tiles appear in the Liveboard Agent panel as AI-generated data insight cards that users can interact with. -[discrete] -==== Liveboard browser cache refresh -To improve load performance and reduce, you can now enable the Liveboard cache option with a **Refresh** button to allow your users to clear cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Liveboard browser cache refresh]. +The Visual Embed SDK 1.51.0 extends `SpotterVizConfig` with two new properties for the SpotterViz loading state: ---- +* `loaderHeadline` — Custom headline text displayed while SpotterViz is loading. +* `loaderTips` — Custom array of tips (`SpotterVizLoaderTip[]`) shown during the loading state. -[discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. +For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. --- [discrete] -==== REST API v2 -This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -|===== - - -== May 2026 +==== Spotter onboarding starter prompts [.version-badge.new]#New# +// SOURCE: SCAL-293483, SCAL-314448 +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl +// TODO: [WRITER] Verify that customStarterPrompts is supported in SpotterEmbed (in addition to LiveboardEmbed and AppEmbed) by checking the SDK source for SpotterEmbedViewConfig. +Embedded Spotter now supports onboarding starter prompts to guide first-time users. When enabled, Spotter presents suggested questions based on the connected data model. Use `enableStarterPrompts: true` in `SpotterChatViewConfig` to enable this feature. -**Release version**: ThoughtSpot Cloud 26.5.0.cl + -*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + -*Recommended SDK versions*: Visual Embed SDK v1.48.0 and later - - -[.cl-table, cols="2,4", frame=none, grid=none] -|===== -a| -[.cl-label] -*Version 26.5.0.cl* - -a| - - -[discrete] -==== Liveboard downloads - -Continuous Liveboard PDF export [beta betaBackground]^Beta^:: -In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. - -Liveboard download in XLSX and CSV formats:: -Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. - -Excel exports for pivot tables:: -Pivot table visualizations can now be exported to Excel format. - -For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard download options]. - ---- - -[discrete] -==== Visualization edit interface within the Liveboard view - -Users can now edit the underlying query of an answer directly within the Liveboard. When this feature is enabled, the edit button for visualization appears in the answer's floating toolbar when the Liveboard is opened in the edit mode. Clicking the edit button opens the Answer interface preloaded with the answer's current query context. You can make the edits and save the changes without leaving the Liveboard. +For more information, see xref:embed-spotter.adoc#_enable_starter_prompts[Enable starter prompts in Spotter]. --- [discrete] -==== KPI charts in embedded Liveboards +==== Navigation and homepage V1/V2 deprecated [.version-badge.deprecated]#Deprecated# +// SOURCE: SCAL-312731 +// TODO: [WRITER] Confirm exact release in which V1 and V2 will be fully REMOVED (not just deprecated) with the product team. Update the phrase "a future release" with the specific version once confirmed. +// TODO: [WRITER] Verify with SDK team whether existing embeds that omit discoveryExperience automatically fall back to V3, or require explicit SDK configuration. +Starting from ThoughtSpot Cloud 26.8.0.cl, the classic V1 and V2 navigation and homepage experience modes are deprecated. All ThoughtSpot Embedded sessions now render in the V3 navigation experience by default. -Embedded Liveboards support advanced controls KPI chart customization. For more information, see link:https://docs.thoughtspot.com/cloud/latest/chart-kpi#advanced[KPI charts]. +ThoughtSpot recommends updating your embed configuration to set `discoveryExperience` explicitly with `PrimaryNavbarVersion.Sliding` and `HomePage.ModularWithStylingChanges` to ensure compatibility with future releases. ---- - -[discrete] -==== Per-org and per-user timezone control via variables [beta betaBackground]^Beta^ - -You can centrally control timezone behavior per org and per user in embedded deployments using the new template variable `ts_user_timezone` and Variable APIs. - -For multi-org and multi-tenant environments, each tenant org and user can be configured independently, guaranteeing isolation and consistency of time-based analytics across regions. Administrators can reference the timezone variable in formulas to render and filter timestamp data correctly for each embedded user, without separate content per region. +For migration guidance, see xref:full-app-customize.adoc#nav-v1-v2-deprecation[V1 and V2 deprecation]. --- [discrete] -==== Timezone-aware keyword filtering [beta betaBackground]^Beta^ -ThoughtSpot now supports resolving relative date and time keywords, such as `today`, `yesterday`, and `last 7 days`, using a configurable per-user or per-Org timezone, instead of the system default timezone on a ThoughtSpot instance. This feature eliminates timezone-based inconsistencies in multi-region embedded deployments and removes the need for custom workarounds. +==== TSE: Multiple features now generally available +// SOURCE: SCAL-295712 +// TODO: [WRITER] Confirm with product team the exact set of features going GA in 26.8.0.cl. The list below is based on SCAL-295712 description. Verify: Hide Irrelevant Filters, Compact Header, Cover Filter Page, Aether UI are all included. +The following features, previously in Early Access, are now generally available for ThoughtSpot Embedded instances: -For more information, see xref:timezone.adoc[Timezone-aware keywords and filters]. - -[NOTE] -==== -The timezone awareness feature is in Beta and disabled by default. To enable this feature, contact ThoughtSpot Support. -==== +* *Hide Irrelevant Filters* — Filters that are not relevant to the displayed visualization are automatically hidden. +* *Compact Header* — A condensed header layout for embedded Liveboards. +* *Cover Filter Page* — Overlay filter page experience for Liveboards. +* *Aether UI* — Updated visual design system. +No SDK configuration changes are required. These features are enabled by default for all embedded instances on 26.8.0.cl. --- [discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.48.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. +==== WYSIWYG Liveboard PDF export [.version-badge.new]#New# +// SOURCE: SCAL-309481 +// TODO: [WRITER] Verify whether `isContinuousLiveboardPDFEnabled` (introduced in SDK 1.48.0 beta) is the same feature going GA in 26.8.0.cl, or a separate capability. Confirm with the Liveboard team. +// TODO: [WRITER] Verify backward compatibility: confirm whether existing `DownloadLiveboardAsContinuousPDF` action behavior is unchanged for embeds using SDK 1.48.x+. +The WYSIWYG Liveboard PDF export experience is now generally available for ThoughtSpot Embedded instances. When this feature is enabled, the exported PDF matches the exact Liveboard layout as displayed on screen, rendering visualizations in a continuous layout rather than splitting them across A4 pages. --- [discrete] -==== REST API v2 -This release introduces new Spotter API endpoints and modifications to the agent conversation APIs, and deprecates legacy agent endpoints. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -|===== +==== Granular download privileges [.version-badge.new]#New# +// SOURCE: SCAL-273333 +// TODO: [WRITER] Confirm exact privilege names displayed in the UI ("Can Download Visuals" and "Can Download Detailed Data") and their corresponding REST API enum values with the access control team. +// TODO: [WRITER] Confirm whether existing "Can download" privilege assignments are automatically migrated to both new privileges, or require manual re-assignment. +ThoughtSpot introduces two new granular download privileges that replace the single general download privilege: +* *Can Download Visuals* — Allows downloading chart images and visual exports. +* *Can Download Detailed Data* — Allows downloading raw tabular data (CSV, XLSX). -== April 2026 - -**Release version**: ThoughtSpot Cloud 26.4.0.cl + -*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + -*Recommended SDK versions*: Visual Embed SDK v1.47.0 and later - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== - -a| -[.cl-label] -*Version 26.4.0.cl* - -a| - -[discrete] -==== Theme builder in AI mode - -The Theme Builder now has an AI mode that enables developers to explore and preview style customizations for their embedded application’s branding using natural language instructions and uploaded brand assets. You can execute style updates such as applying colors directly from a PDF branding guide, updating all button shapes with higher contrast, matching a header to a dark background based on a screenshot, or importing typography and spacing from a JSON file. In the AI mode, Theme builder interprets your intent and applies the changes instantly. - -For more information, see xref:theme-builder.adoc[Theme builder]. +These privileges can be assigned independently per user or group. Update privilege assignments in your embedded application accordingly. --- - [discrete] -==== Webhook integration -In this release version, the following enhancements are introduced in the webhook configuration and delivery status monitoring workflows: +==== Personalized Views portability [.version-badge.new]#New# +// SOURCE: SCAL-307283 +// TODO: [WRITER] Confirm exact TML field names `owned_by` and `obj_id` in the Personalized View TML schema with the TML/deployment team (Rajesh / Platform team) before publishing. +// TODO: [WRITER] Confirm the import merge behavior — does a duplicate check on `obj_id` prevent duplicate creation, or does it update the existing view? +ThoughtSpot improves the portability of Personalized Views across environments: -Channel validation:: -Administrators can verify the connection status of a webhook channel by sending a test payload in a `POST` request to the `/api/rest/2.0/system/communication-channels/validate` REST API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[Webhook channel validation]. +* A new `owned_by` field in the Personalized View TML allows specifying the owner during import. +* Personalized Views now support `obj_id` for stable cross-environment object identity. +* Import operations use smart merge logic to avoid duplicating Personalized Views with matching identity. -Monitor webhook delivery:: -Administrators can also monitor the status of a webhook delivery via a `POST /api/rest/2.0/jobs/history/communication-channels/search` API request. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. - -Support for custom HTTP headers in webhook requests:: -When configuring or updating a webhook, you can now specify custom headers to include in every outbound request, in addition to the standard HTTP and authentication headers that ThoughtSpot sends. For more information, refer to the xref:webhooks-lb-schedule.adoc#_create_a_webhook[webhook documentation]. +For more information, see xref:tml.adoc[TML import and export]. --- - [discrete] -==== Spotter embed enhancements -You can now customize the appearance and contents of the chat history sidebar panel in Spotter embedding. +==== Collections `obj_id` support in TML [.version-badge.new]#New# +// SOURCE: SCAL-317357 +// TODO: [WRITER] Verify the exact REST API endpoint path for updating Collections obj_id with the platform team. Candidate path: POST /api/rest/2.0/metadata/identity/update — confirm this is correct and supported for Collections. +The `obj_id` attribute is now supported for the *Collections* object type in TML import and export. This enables stable cross-environment identification for Collections, consistent with support already available for other object types such as Models, Liveboards, and Answers. -You can also customize the branding and logo in the Spotter chat interface. +The Metadata Identity Update API is extended to support updating `obj_id` for Collections. -For more information, see xref:embed-spotter.adoc#_chat_history_panel[Customizing chat history sidebar] and xref:embed-spotter.adoc#_hiding_the_spotter_icon_and_thoughtspot_branding_chat_interface[Hiding logo and brand label in Spotter chat interface]. +For more information, see xref:tml.adoc[TML import and export]. --- [discrete] -==== Liveboard enhancements -The following enhancements are introduced in Liveboard export and filtering workflows. - -Embedding a personalized Liveboard view:: -You can now embed a saved personalized Liveboard view using the `personalizedViewId` and load it along with the `liveboardId` in your app. +==== Discoverability checkbox removed [.version-badge.breaking]#Breaking# +// SOURCE: SCAL-292918 +// TODO: [WRITER] Verify whether the `discoverable` field in REST API share requests is also removed or deprecated, or whether the API still accepts it silently. +The *Make this Liveboard Discoverable* checkbox has been removed from the ThoughtSpot UI. Content is no longer made discoverable through a toggle. Sharing and access control are now managed exclusively through explicit sharing workflows. -Centralized filter modal:: -Liveboard users can modify multiple filters and parameters in a single session using the centralized filter modal. This is an early access feature and disabled by default on ThoughtSpot embedded instances. To enable this feature on embedded Liveboards, set the `isCentralizedLiveboardFilterUXEnabled` to `true`. - -Current period inclusion in rolling date filters:: -The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. - -Liveboard PNG export:: -The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API documentation]. +Embedding applications that relied on discoverability for content visibility should review their sharing logic and update user-facing guidance for content access. --- - [discrete] -==== Full app embedding -In full application embedded deployments with the V3 navigation and home page experience, the default list page experience is set to ListPage v3 experience. - -The ListPage V3 experience provides a refreshed list layout and styling, including the following enhancements: - -* The **Views** column to show the number of views for each object. -* Sorting options for **Name**, **Author**, and **Views** columns. -* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. +==== Schedule every-N-minutes option deprecated [.version-badge.deprecated]#Deprecated# +// SOURCE: SCAL-244749 +// TODO: [WRITER] Confirm which release the every-N-minutes frequency option will be fully removed with the Schedules team. Also confirm whether existing schedules are automatically migrated to the next supported frequency. +The *every N minutes* frequency option for Liveboard scheduled jobs is deprecated in 26.8.0.cl. New scheduled jobs cannot be created with this frequency. Existing jobs configured with this frequency continue to run until they are edited or the option is removed in a future release. -For more information, see xref:full-app-customize.adoc#_customize_list_page_experience[List page customization]. +Embedding applications that create scheduled jobs programmatically via the REST API should remove any usage of the `every_n_minutes` frequency in schedule creation requests. --- - [discrete] -==== Variable API -The variable REST API provides new API endpoints for the following bulk operations: - -* Bulk deletion: -You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. -* Batch update of variable values: -You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. - -[NOTE] -==== -The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. -==== - -For more information, see xref:variables.adoc[Variables documentation]. +==== Business Terms autogeneration deprecated [.version-badge.deprecated]#Deprecated# +// SOURCE: SCAL-313088 +// TODO: [WRITER] Confirm whether existing auto-generated business terms are preserved or removed after this deprecation. Confirm which Spotter coaching REST API endpoints are affected (SCAL-313088 does not include an API spec). +The automatic generation of Business Terms for Spotter model coaching is deprecated. The Business Terms fields in the Spotter coaching interface are now available exclusively for adding custom context. Administrators who manage Spotter model coaching should review existing business term configurations. --- - [discrete] -==== Metadata parameterization -You can now parameterize multiple properties of metadata objects using `POST /api/rest/2.0/metadata/parameterize-fields`. The legacy endpoint `/api/rest/2.0/metadata/parameterize` is deprecated in 26.4.0.cl and later versions, and is replaced with the new endpoint to allow updating multiple fields in a single API request. - -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization documentation]. +==== Spotter Model [.version-badge.new]#New# +// SOURCE: SCAL-306340 +// TODO: [WRITER] Confirm whether Spotter Model GA milestone is 26.8.0.cl or jun.26.mt (the Jira fix version field is ambiguous). Verify with the AI Modeling team before publishing. +// TODO: [WRITER] Add xref to the Spotter Model page in developer-docs once the page filename is confirmed. +Spotter Model — which allows administrators to configure, train, and manage a dedicated AI model for Spotter — is now generally available. For more information, see the Spotter Model documentation. --- - -[discrete] -==== Collections [beta betaBackground]^Beta^ -ThoughtSpot embedded users can now use REST APIs v2 to organize different ThoughtSpot objects into organizational containers called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. - -For more information, see xref:collections.adoc[Collections]. - -[NOTE] -==== -These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. -==== ---- - [discrete] ==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, SpotterViz loading state customization, and the `HostEvent.Navigate` object format. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +--- [discrete] ==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- -|=== -== March 2026 +|===== -**Release version**: ThoughtSpot Cloud 26.3.0.cl + -*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + -*Recommended SDK versions*: Visual Embed SDK v1.46.0 and later +== July 2026 -[.cl-table, cols="2,4", frame=none, grid=none] -|=== +**Release version**: ThoughtSpot Cloud 26.7.0.cl + +*Upgrade notes*: No breaking changes + +*Recommended SDK versions*: Visual Embed SDK v1.50.0 and later +[.cl-table, cols="2,4", frame=none, grid=none] +|===== a| [.cl-label] -*Version 26.3.0.cl* +*Version 26.7.0.cl* a| [discrete] -==== Amazon S3 storage destination for webhook delivery -You can now configure ThoughtSpot to deliver webhook payloads and attachments directly into your own Amazon S3 storage using secure AWS cross-account access. To enable this integration, your AWS administrator must create an IAM role with S3 permissions and trust policy, and then register a webhook in ThoughtSpot to deliver the payloads and attachments directly to your S3 bucket. - -For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. - ---- - -[discrete] -==== Host event enhancements for context-aware routing - -HostEvents in the Visual Embed SDK are enhanced to improve event routing and context targeting in ThoughtSpot embedded applications. - -Developers can use the page context framework in the SDK to route host events to a specific UI layer and align user experience with the product UI behavior in multi-modal contexts. - -For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. - ---- - -[discrete] -==== JWT-based ABAC implementation -The legacy JWT-based approach that uses `filter_rules` and `parameter_values` to implement Attribute-Based Access Control (ABAC) is deprecated. - -As part of this deprecation, the following changes have been introduced to the custom authentication token API workflow and REST API Playground: - -* The `filter_rules` parameter on the custom token authentication page in the REST API Playground is no longer available for new configurations. This change does not affect your existing implementation. - -* The `parameter_values` property is not deprecated in version 26.3.0.cl and remains supported until further notice. However, using parameter values for row-level security use cases will ultimately be deprecated in an upcoming release. - -Existing ABAC implementations that use `filter_rules` will continue to function until further notice. However, we strongly recommend migrating your legacy ABAC implementation to the ABAC via RLS method that uses custom variables. For migration steps, refer to the xref:abac-migration-guide.adoc[ABAC migration guide]. - -For new deployments, use ABAC via RLS with custom variables and pass data security attributes through the `variable_values` property in the custom access token, and define your RLS rules based on those variables. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS]. - ---- - -[discrete] -==== Spotter coaching access across published Orgs -Starting with the 26.3.0.cl release, ThoughtSpot supports publishing Spotter coaching information to other Orgs. Coaching changes from the primary Org are synchronized with the data models published in secondary Orgs. - -Administrators and users with edit access to data models can programmatically control user access to Spotter coaching information using the object privilege REST API endpoint, `/api/rest/2.0/security/metadata/manage-object-privilege`. They can assign `SPOTTER_COACHING_PRIVILEGE` to other users and user groups, allowing access to the coaching information without requiring data model editing or administration privileges. - -Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. +==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# +You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. -For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. +For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. --- [discrete] -==== Full application embedding -The height and aspect ratio of the logo in the top-left corner of the ThoughtSpot application interface have been updated for visual alignment and consistency across pages. This enhancement is available only in the V3 navigation and home page experience. - -If you have embedded the full application with the V3 navigation experience, you may notice that the logo appears smaller in the top navigation. This is a design update and does not require any configuration changes to your current embedding implementation. However, we recommend that you review the logo size and appearance, and adjust your custom logo if necessary. - -For information about adding a custom logo image, see xref:customize-style.adoc#logo-change[Customize application logo and favicon]. - ---- +==== Spotter embedding -[discrete] -==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. +Spotter file upload in embedded apps:: +Applications embedding the Spotter interface can now allow their users to xref:embed-spotter.adoc#_enable_file_upload_in_spotter_chat[upload files directly in the Spotter chat panel]. ---- +Spotter conversation history:: +You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. -[discrete] -==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +Spotter Agent instructions:: +You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. --- -|=== - -== February 2026 -**Release version**: ThoughtSpot Cloud 26.2.0.cl + -*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + -*Recommended SDK versions*: Visual Embed SDK v1.45.0 and later - - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.2.0.cl* - -a| [discrete] -==== 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. +==== Focused home page experience [earlyAccess eaBackground]#Early Access# -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]. +In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. --- [discrete] -==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# -You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an 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]. - ---- +==== Webhooks enhancements -[discrete] -==== 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. +ThoughtSpot introduces the following features and enhancements for webhook configuration and management: -For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. +* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + +The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. +* Storage configuration retrieval + +The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. +* GCS storage configuration for webhook delivery + +Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. +* Webhook activation and deactivation + +You can enable or disable a webhook connection in the UI or through REST API. +* Selective configuration reset + +The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. --- [discrete] -==== Security settings via REST APIs -Security settings that ensure data security and a seamless embedded user experience can now be configured through REST APIs v2. Administrators and developers can configure allowlists for: +==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# -* Content Security Policy (CSP) -* Cross-origin Resource Sharing (CORS) -* Authentication attributes -* Access control settings +The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically, accelerates building code and iterating embed configurations. -For more information, see xref:security-settings.adoc[Security Settings]. +For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. --- [discrete] -==== WebSocket support for external tools -ThoughtSpot supports secure WebSocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. - -To allow a WebSocket host, add the corresponding `wss://` URL to both your CSP allowlists. Only hosts explicitly listed with the `wss://` protocol are permitted. Existing `https://` entries in the allowlists remain unchanged and continue to function as expected. - -For more information, see xref:3rd-party-script.adoc#_allow_websocket_endpoints[External tools and script integration]. +==== Org isolation for per-org SAML and OIDC authentication +ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. --- - [discrete] ==== 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]. +The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- -|=== +|===== -== January 2026 +== June 2026 -**Release version**: ThoughtSpot Cloud 10.15.0.cl + +**Release version**: ThoughtSpot Cloud 26.6.0.cl + *Upgrade notes*: No breaking changes. + -*Recommended SDK versions*: Visual Embed SDK v1.44.0 and later - +*Recommended SDK versions*: Visual Embed SDK v1.49.0 and later [.cl-table, cols="2,4", frame=none, grid=none] -|=== +|===== a| [.cl-label] -*Version 10.15.0.cl* +*Version 26.6.0.cl* a| [discrete] -==== Theme Builder -Theme Builder is now generally available (GA) and will be rolled out to all ThoughtSpot instances in customer deployments over the next few weeks. - -When this feature is enabled on your instance, you can access it from the *Develop* page in ThoughtSpot and use it to customize styles and UX themes directly within the product. - -For more information, see xref:theme-builder.adoc[Theme Builder]. - ---- - -[discrete] -==== V3 navigation and home page experience - -The new V3 navigation and home page experience is now generally available (GA) and can be enabled on ThoughtSpot embedded instances. - -The default UI experience in full application embedding remains the classic (V1) experience until further notice. Developers embedding the full ThoughtSpot application can enable the V3 experience in their applications by setting the appropriate configuration options in their embed code. - -For more information, see xref:full-app-customize.adoc[Customizing full application embedding]. - ---- - -[discrete] -==== Formula variables in RLS rules +==== Chart and table overrides [.version-badge.new]#New# +You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: -You can now create formula variables using the Variable REST API and use these variables in RLS rules for a specific data context and in ABAC token requests to dynamically assign security attributes to users. +* Chart overrides + +Control legend visibility and position, data label display and per-column filter +thresholds, regression lines, grid lines, axis range and label settings, series +colors, and conditional formatting rules including font and background styling. +* Table overrides + +Control column visibility, text wrapping, row height and padding density, table +theme, and column summary visibility with per-column exceptions. -For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. +For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. --- [discrete] -==== Spotter APIs - -ThoughtSpot introduces new REST APIs for the following Spotter workflows: - -* To send queries to a conversation session with the Spotter agent -* To set natural language (NL) instructions on a model to coach the Spotter system -* To fetch NL instructions configured on a model - -For more information, see xref:spotter-apis.adoc[Spotter APIs]. +==== Spotter AI and embedding enhancements [.version-badge.new]#New# ---- +This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. -[discrete] -==== Embed events and parameters to intercept API calls -You can now intercept API calls from the embedded ThoughtSpot application using the `interceptUrls` attribute in the Visual Embed SDK. This feature lets you control API requests in your embedding application and use embed events to modify, block, or handle requests before they are sent to the backend. For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. +* Spotter embedding: + +Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. ---- +* Spotter embedding in AppEmbed: + +The `AppEmbed` component now supports Spotter sidebar configuration through the `spotterSidebar` object. For more information, see xref:embed-spotter.adoc[Embed Spotter experience]. -[discrete] -==== Icon customization enhancements +* Action IDs for Spotter chat UI elements: + +The SDK introduces new action IDs to control the visibility of specific UI components in the chat panel: +** `Action.SpotterChatConnectorResources` — For the connector resources section. +** `Action.SpotterChatConnectors` — For the connectors panel. +** `Action.SpotterChatModeSwitcher` — For the mode switcher. -You can now replace or customize the chart switcher toggle and icons in the Charts drawer on an Answer or visualization page using SVG sprites. Previously, these icons were fixed to ThoughtSpot defaults and were not configurable. In the new version, these icons are available as SVG components and can be replaced by developers through the xref:customize-icons.adoc[icon customization framework] as needed. +For more information, see xref:embed-spotter.adoc[Embed Spotter experience]. --- [discrete] -==== Mobile Embed SDK -The SDKs for embedding ThoughtSpot components in mobile apps are now Generally Available (GA). For more information about the SDKs and how to embed a ThoughtSpot component in a mobile app, see xref:mobile-embed.adoc[Mobile embed documentation]. +==== Visual Embed SDK +The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. --- [discrete] -==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. +==== REST API v2 +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- -[discrete] -==== REST API -For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -|=== \ No newline at end of file +|===== From 7bf89c9796b17457bed6e6fd89e614b0ee1faff4 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:15:27 +0530 Subject: [PATCH 02/63] =?UTF-8?q?docs(sdk-changelog):=20Add=20Visual=20Emb?= =?UTF-8?q?ed=20SDK=201.51.0=20changelog=20entries=20=E2=80=94=20Spotter?= =?UTF-8?q?=20Analysts=20labels,=20enableStarterPrompts,=20SpotterViz=20lo?= =?UTF-8?q?aderHeadline/loaderTips,=20HostEvent.Navigate=20object=20format?= =?UTF-8?q?=20[SCAL-310399,=20SCAL-312622,=20SCAL-293483,=20SCAL-309017]"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/api-changelog.adoc | 1890 +++---------------------- 1 file changed, 181 insertions(+), 1709 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index da7ec9f9f..3247a3758 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,186 @@ This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +// ============================================================ +// SOURCE: src/embed/conversation.ts, src/embed/spotter-viz-utils.ts, +// src/embed/app.ts, src/embed/liveboard.ts +// (visual-embed-sdk main branch, verified 2026-07-10) +// SOURCE: SCAL-310399, SCAL-312622, SCAL-293483, SCAL-309017 +// TODO: [WRITER] Confirm calendar month label — "August 2026" if release ships in +// late July / early August 2026. Verify with release team. +// TODO: [WRITER] Confirm whether Action enum values for Analyst actions +// (Action.ShowAnalysts, Action.CreateAnalyst, Action.EditAnalyst, +// Action.MakeCopyAnalyst, Action.ShareAnalyst, Action.DeleteAnalyst) +// are present in the released types.ts for SDK 1.51.0. They are referenced +// in SCAL-312622 but were not confirmed in types.ts source at time of authoring. +// Run a grep on the tagged SDK 1.51.0 release before publishing. +// ============================================================ + +== Version 1.51.x, August 2026 + +[width="100%", cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Spotter Analysts — SDK configuration controls +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl +// SOURCE: SCAL-310399, SCAL-312622 +The Visual Embed SDK 1.51.0 introduces controls for the Spotter Analysts feature in embedded applications. The Analysts section in the Spotter sidebar is disabled by default in TSE mode. + +New properties in `SpotterSidebarViewConfig` (supported on `SpotterEmbed`, `LiveboardEmbed`, and `AppEmbed`): + +`spotterAnalystLabel`:: +Custom singular label for the Analyst entity shown in the sidebar. + +Default: `"Analyst"` + +`@version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl` + +`spotterAnalystsLabel`:: +Custom label for the Analysts sidebar section header. + +Default: `"Analysts"` + +`@version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl` + +New property in `SpotterChatViewConfig`: + +`enableStarterPrompts`:: +// SOURCE: src/embed/conversation.ts — SpotterChatViewConfig.enableStarterPrompts +When set to `true`, displays onboarding starter prompts in the Spotter chat interface on initial load. Supported on `SpotterEmbed`, `LiveboardEmbed`, and `AppEmbed`. + +Default: `false` + +`@version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl` + +New action IDs for `disableActions` and `hideActions` (Analyst actions): + +// TODO: [WRITER] Verify these Action enum values exist in the SDK 1.51.0 release of types.ts. +// Source: SCAL-312622 Jira description (not yet confirmed in types.ts grep). +[width="100%", cols="2,4"] +|==== +|Action ID |Description +|`Action.ShowAnalysts` |Controls visibility of the Analysts section in the sidebar. +|`Action.CreateAnalyst` |Controls the Create Analyst action. +|`Action.EditAnalyst` |Controls the Edit Analyst action. +|`Action.MakeCopyAnalyst` |Controls the Make a Copy action. +|`Action.ShareAnalyst` |Controls the Share Analyst action. +|`Action.DeleteAnalyst` |Controls the Delete Analyst action. +|==== + +Example — embed Spotter with custom Analyst labels and restricted actions: + +[source,JavaScript] +---- +import { + SpotterEmbed, + Action, + AuthType, + init, +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/token').then(r => r.json()).then(d => d.token), +}); + +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + spotterSidebar: { + spotterAnalystLabel: 'Assistant', // Default: "Analyst" + spotterAnalystsLabel: 'My Assistants', // Default: "Analysts" + }, + spotterChat: { + enableStarterPrompts: true, // Default: false + }, + hideActions: [ + Action.CreateAnalyst, + Action.DeleteAnalyst, + ], +}); + +spotterEmbed.render(); +---- + +For more information, see xref:embed-spotter.adoc#spotter-analysts[Spotter Analysts in embedded applications]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== SpotterViz loading state customization +// SOURCE: src/embed/spotter-viz-utils.ts @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl +// SOURCE: SCAL-309017 +The Visual Embed SDK 1.51.0 extends the `SpotterVizConfig` interface with two new properties for customizing the SpotterViz panel loading state on embedded Liveboards and full-application embeds. + +`loaderHeadline`:: +Custom headline text shown in the SpotterViz loading state. Replaces the default loading headline. + +`@version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl` + +`loaderTips`:: +Custom array of `SpotterVizLoaderTip` objects displayed as tips during the SpotterViz loading state. Replaces the default loading tips. + +`@version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl` + +`SpotterVizLoaderTip` interface: + +[source,TypeScript] +---- +interface SpotterVizLoaderTip { + label: string; // Short label rendered alongside the tip (e.g., "Tip") + text: string; // Tip body text +} +---- + +Example usage: + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '<%=liveboardGUID%>', + spotterViz: { + brandName: 'MyBrand', + brandHeadline: "Hi, I'm", + description: 'Ask questions about your data', + inputChatPlaceholder: 'What would you like to know?', + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + loaderHeadline: 'Crunching the numbers...', + loaderTips: [ + { label: 'Tip', text: 'Try asking about revenue by region' }, + { label: 'Tip', text: 'Use natural language — no SQL needed' }, + { label: 'Tip', text: 'Ask for comparisons, trends, and breakdowns' }, + ], + }, + frameParams: { width: '100%', height: '100%' }, +}); + +embed.render(); +---- + +// TODO: [WRITER] Confirm with the SpotterViz team whether there is a maximum +// recommended or enforced limit on the number of loaderTips entries. + +For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== HostEvent.Navigate — object format support +// SOURCE: src/types.ts (visual-embed-sdk main) — HostEvent.Navigate object format comment +// SOURCE: SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl (confirmed from types.ts source) +The `HostEvent.Navigate` event now supports an object format in addition to the existing string path format. Use the object format to replace the current browser history entry instead of pushing a new entry. + +[source,JavaScript] +---- +// String format — push new history entry (existing behavior, unchanged) +appEmbed.trigger(HostEvent.Navigate, 'home'); + +// Object format — replace current history entry (new in SDK 1.51.0) +appEmbed.trigger(HostEvent.Navigate, { path: 'home', replace: true }); +---- + +Supported embed types: `AppEmbed`. + +// TODO: [WRITER] Confirm whether `replace: false` is a valid option (push behavior) +// or whether omitting `replace` defaults to push behavior. + +|==== + == Version 1.50.x, July 2026 @@ -154,1714 +334,6 @@ EmbedEvent:: * `EmbedEvent.Subscribed` + The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. * `EmbedEvent.Error` + -The `EmbedEvent.Error` now fires on HostEvent payload validation failures. -* `EmbedEvent.ChangePersonalizedView` + -Emits when a user selects a different Personalized View or resets to default. - -HostEvent:: -* `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + -The response payload of the `GetExportRequestForCurrentPinboard` passthrough -host event has been updated to include a `type` discriminator field, making it -consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. - -* `HostEvent.SelectPersonalizedView` + -Triggers the selection of a specific Personalized View and resets the default view on a Liveboard. - -⚠️Deprecated events and action IDs️:: -The following events are deprecated and replaced with new event IDs. - -* `EmbedEvent.UpdatePersonalisedView`. Use `EmbedEvent.UpdatePersonalizedView`. -* `EmbedEvent.SavePersonalisedView`. Use `EmbedEvent.SavePersonalizedView`. -* `EmbedEvent.DeletePersonalisedView`. Use `EmbedEvent.DeletePersonalizedView`. -* `HostEvent.ResetLiveboardPersonalisedView`. Use `HostEvent.ResetLiveboardPersonalizedView`. -* `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. -* `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. - - -|==== - - -== Version 1.47.x, April 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** - -The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: - -* `enablePastConversationsSidebar` + -Controls the visibility of the past conversations sidebar panel. The chat history panel is disabled by default in embed view. When this property in `spotterSidebarConfig` is specified, it takes precedence over the standalone `enablePastConversationsSidebar` setting, which is deprecated from v1.47.0. - -* `spotterSidebarTitle` + -Allows adding custom title text for the sidebar header. - -* `spotterSidebarDefaultExpanded` + -Sets the default state of the sidebar to expanded or collapsed view. - -* `spotterChatRenameLabel` + -Allows setting a custom label for the **Rename** action in the conversation edit menu. - -* `spotterChatDeleteLabel` + -Allows setting a custom label for the **Delete** action in the conversation edit menu. - -* `spotterDeleteConversationModalTitle` + -Allows editing the title text of the chat delete confirmation modal. - -* `spotterPastConversationAlertMessage` + -Sets a custom message text for the past conversation banner alert. Defaults to the translated alert message. - -* `spotterBestPracticesLabel` + -Allows customizing the label for the best practices button in the sidebar footer. - -* `spotterDocumentationUrl` + -The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. - -* `spotterConversationsBatchSize` + -Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. - -* `spotterNewChatButtonTitle` + -Allows customizing the title text for the **New chat** button in the sidebar. - -|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** - -The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. - -Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. - -[source,javascript] ----- -// Deprecated -enablePastConversationsSidebar: false, - -// Recommended -spotterSidebarConfig: { - enablePastConversationsSidebar: true, - //... other config properties -} ----- - -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** - -The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. - -* `hideToolResponseCardBranding` + -When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. - -* `toolResponseCardBrandingLabel` + -Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. - -[NOTE] -==== -These settings do not affect the external MCP tool branding. -==== - -|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** - -Personalized Liveboard view:: - -The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. - -Centralized Liveboard filter setting:: - -When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. - -|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** - -If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. -To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. -|==== - - -== Version 1.46.x, March 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** - -The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. - -* To enable this feature, set `useHostEventsV2` to `true`. -* To retrieve the current context, use `getCurrentContext()`. -* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. - -For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. - -|[tag redBackground]#DEPRECATED# a| **dataPanelV2** - -The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. - -|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** -The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. - -Chat history sidebar customization:: - -//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. -//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. -* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: -** `Action.DataModelInstructions` for the data model instructions icon. -** `Action.SpotterSidebarHeader` for the chat history sidebar header -** `Action.SpotterSidebarFooter` for the chat history sidebar footer -** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. -** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. -** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. -** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. -** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. -** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. -//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. - -Events:: -* `HostEvent.DataModelInstructions` + -Opens the Data Model instructions modal. -* `EmbedEvent.DataModelInstructions` + -Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. -* `EmbedEvent.SpotterConversationRenamed` + -Is emitted when a user renames a saved chat. -* `EmbedEvent.SpotterConversationDeleted` + -Is emitted when a saved chat is deleted. -* `EmbedEvent.SpotterConversationSelected` + -Is emitted when a saved chat is selected in the chat history sidebar. - -|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + - -Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. - -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** - -* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. -* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. -|==== - -== 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 `auto_mode`. -* 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. - -[NOTE] -==== -On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. -==== - -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + - -Styling and grouping:: +The `EmbedEvent.Error` event now includes an error code in the payload for more specific error identification. -* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute 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 *Manage publishing* -* `Action.Unpublish` for *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`, and `NETWORK`. -* `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"] -|==== - -|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + - -The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. -To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. - -|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + -The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: - -//* `enableApiIntercept` + -//When set to true, enables the feature on your ThoughtSpot embed. -* `interceptUrls` + -Allows configuring which API calls to intercept. -* `interceptTimeout` + -Sets the timeout duration for handling interception. -* `isOnBeforeGetVizDataInterceptEnabled` + -When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. -* `EmbedEvent.ApiIntercept` + -Emits when an API call matching the conditions defined in `interceptUrls` is detected. - -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"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* - -The following enumerations are available for code-based custom actions: - -* `CustomActionTarget` + -To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. -* `CustomActionsPosition` + -To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. -|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + -The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. -|==== - -== Version 1.42.0, October 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* - -The Visual Embed SDK now supports runtime overrides in Spotter embed. - -* To apply runtime filters, use the `runtimeFilters` object -* To apply runtime Parameters, use the `runtimeParameters` object. - -|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + -To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. - -The SDK also provides the following action IDs: - -* `Action.PngScreenshotInEmail` + -Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. -* `Action.RemoveAttachment` + -Allows the user to remove an attachment from the email configuration in the schedule email dialog. -|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* - -Action IDs:: -The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: - -* `Action.SpotterWarningsBanner` + -Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. -* `Action.SpotterWarningsOnTokens` + -Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. -* `Action.SpotterTokenQuickEdit` + -Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. -|==== - -== Version 1.41.0, September 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* - -The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. - -For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. - -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* - -The following event handlers are now available for Spotter embed: - -* `EmbedEvent.SpotterInit` + -Fires when Spotter embed component rendering is initialized. -* `EmbedEvent.QueryChanged` + -Fires when the Spotter query is updated by the user. -* `HostEvent.AskSpotter` + -Triggers *Ask Spotter* action for visualizations. -* `HostEvent.GetParameters` + -Triggers the action to fetch runtime Parameters applied on a visualization. -* `HostEvent.UpdateParameters` + -Triggers the action to update runtime Parameters for a Spotter-generated Answer. -* `HostEvent.GetTML` + -Triggers the action to get TML representation of a Spotter-generated Answer. - -For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* - -You can now use the following host events in Spotter Agent embedding: - -- `HostEvent.DownloadAsCsv` + -Triggers the action to download a Spotter-generated Answer in CSV format. -- `HostEvent.DownloadAsPng` + -Triggers the action to download a Spotter-generated Answer in PNG format. -- `HostEvent.DownloadAsXlsx` + -Triggers the action to download a Spotter-generated Answer in XLSX format. -- `HostEvent.DownloadAsPdf` + -Triggers the action to download the PDF version of a Spotter-generated Answer. -- `HostEvent.Pin` + -Triggers the action to add a Spotter-generated Answer to a Liveboard. -- `HostEvent.Save` + -Triggers the *Save* action for a Spotter-generated Answer. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* - -You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -You can also set the margin property for lazy loading to define when the visualization should load. - -For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. - -|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + - -You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. - -When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. -|==== - -== Version 1.40.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + -Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. -|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + -Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. - -|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + - -If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. - -For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. - -|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + - -The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. - -|[tag greenBackground]#NEW FEATURE# a| *Host events* + - -In this version, the SDK introduces the following host event handlers: - -- `HostEvent.ExitPresentMode` + -Triggers the exit action that allows users to exit the Liveboard or visualization present mode. -- `HostEvent.SpotterSearch` + -Triggers a search operation for the specified query string in Spotter embed. -- `HostEvent.PreviewSpotterData` + -Triggers the *Preview data* action that shows the data used for Spotter conversations. -- `HostEvent.ResetSpotterConversation` + -Triggers the *Reset* action to reset a Spotter conversation. -- `HostEvent.EditLastPrompt` + -Triggers the edit prompt action. -- `HostEvent.DeleteLastPrompt` + -Triggers the delete prompt action. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* - -You can now use the following host events in Spotter embed: - -- `HostEvent.DownloadAsCsv` -- `HostEvent.DownloadAsPng` -- `HostEvent.DownloadAsXlsx` -- `HostEvent.Edit` -//- `HostEvent.GetParameters` -//- `HostEvent.GetTML` -- `HostEvent.MakeACopy` -- `HostEvent.Pin` -- `HostEvent.Save` - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* - -The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. -This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -[NOTE] -==== -To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. -==== -|==== - - -== Version 1.39.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + -The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: - -* `ConversationEmbed` + -Replaced with `SpotterEmbed` -* `ConversationViewConfig` + -Replaced with `SpotterEmbedViewConfig` -* `BodylessConversation` + -Replaced with `SpotterAgentEmbed` -* `BodylessConversationViewConfig` + -Replaced with `SpotterAgentEmbedViewConfig` - -The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. - -|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + -For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. - -[NOTE] -The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. - -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* - -New embed events:: - -- `EmbedEvent.ExitPresentMode` + -Emits when a user exits the Liveboard or visualization presentation mode. -- `EmbedEvent.LastPromptDeleted` + -Emits when a query prompt in Spotter embed is deleted. -- `EmbedEvent.LastPromptEdited` + -Emits when a query prompt in Spotter embed is edited. -- `EmbedEvent.ResetSpotterConversation` + -Emits when a Spotter query is reset. -- `EmbedEvent.PreviewSpotterData` + -Emits when a user clicks the Preview data button in the Spotter conversation panel. -- `EmbedEvent.SpotterQueryTriggered` -Emits when a Spotter query is triggered. - -The following embed events are also supported in Spotter embed: - -- `EmbedEvent.AddRemoveColumns` -- `EmbedEvent.AnswerChartSwitcher` -- `EmbedEvent.AuthExpire` -- `EmbedEvent.AuthInit` -- `EmbedEvent.CopyToClipboard` -- `EmbedEvent.CustomAction` -- `EmbedEvent.Data` -- `EmbedEvent.DataSourceSelected` -- `EmbedEvent.DialogClose` -- `EmbedEvent.DialogOpen` -- `EmbedEvent.Download` -- `EmbedEvent.DownloadAsCsv` -- `EmbedEvent.DownloadAsPng` -- `EmbedEvent.DownloadAsXlsx` -- `EmbedEvent.DrillDown` -- `EmbedEvent.DrillExclude` -- `EmbedEvent.DrillInclude` -- `EmbedEvent.Edit` -- `EmbedEvent.Error` -- `EmbedEvent.Load` -- `EmbedEvent.Pin` -- `EmbedEvent.Save` -- `EmbedEvent.TableVizRendered` -- `EmbedEvent.VizPointClick` -- `EmbedEvent.VizPointDoubleClick` -- `EmbedEvent.VizPointRightClick` - -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -|==== - -== Version 1.38.0, June 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + -Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. - -To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. - -Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI. - -For more information, see xref:customize-text-strings.adoc[Customize text strings]. - -|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + - -In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: - -* *Author* + -`hiddenListColumns: [ListPageColumns.Author]` -* *Favorite* + -`hiddenListColumns: [ListPageColumns.Favourite]` -* *Last modified* + -`hiddenListColumns: [ListPageColumns.DateSort]` -* *Tags* + -`hiddenListColumns: [ListPageColumns.Tags]` -* *Share* + -`hiddenListColumns: [ListPageColumns.Share]` + - -For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. -|==== - -== Version 1.37.0, April 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. -This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. - -For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. - -|[tag greenBackground]#NEW FEATURE# a| -You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. - -|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: - -Embed Events:: - -* `EmbedEvent.TableVizRendered` + -Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. - -* `EmbedEvent.CreateLiveboard` + -Emits when a Liveboard is created. - -Host Events:: - -* `HostEvent.TransformTableVizData` + -Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. - -* `HostEvent.Remove` + -Triggers the *Delete* action on a Liveboard. |==== - -== Version 1.36.0, February 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The following HostEvents now allow custom parameters to set object properties programmatically: - -* `HostEvent.SaveAnswer` + -Allows adding `name` and `description` text strings. When these parameters are defined, the event triggers the Save action to save the Answer with the predefined properties without opening the *Describe your Answer* modal. -* `HostEvent.Pin` + -Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. - -For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. - -|[tag greenBackground]#NEW FEATURE# a| - -New configuration attributes:: - -* `disableSourceSelection` + -Disables data source selection panel for embed users when set to `true`. -* `hideSourceSelection` + -Hides data source selection panel when set to `true` -* `locale` + -Sets the xref:locale-setting.adoc[locale and regional settings] for the Spotter interface. -* `showSpotterLimitations` + -Shows functional limitations of Spotter when set to `true` -* `hideSampleQuestions` + -Hides sample questions that appear on the default Spotter page. - -Action IDs for menu customization:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions and elements in the embedded Spotter interface: - -* `Action.PreviewDataSpotter` + -The *Preview data* button on the Spotter conversation panel. -* `Action.ResetSpotterChat` + -The *Reset* button on the Spotter conversation panel. -* `Action.SpotterFeedback` + -The feedback widget on Spotter-generated charts. -* `Action.EditPreviousPrompt` + -The edit icon on the prompt panel. -The Prompt panel appears after Spotter generates a response to a user query. -* `Action.DeletePreviousPrompt` + -The delete icon on the prompt panel. - -//// -* `Action.EditTokens` + -The option to edit tokens on a Spotter-generated chart or table. -//// -CSS variables:: - -The following new CSS variables are available for Spotter interface customization: - -* `--ts-var-spotter-input-background` -* `--ts-var-spotter-prompt-background` - -For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. -|[tag greenBackground]#NEW FEATURE# a| - - -Configuration attributes:: - -* `hideIrrelevantChipsInLiveboardTabs` + -Hides filter chips on a Liveboard when set to `true`. - -* `isLiveboardCompactHeaderEnabled` + -Enables the compact Liveboard header feature when set to `true`. - -Action IDs:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: - -* `Action.DisableChipReorder` + -ID for the action that disables filter chip reordering. -* `Action.ChangeFilterVisibilityInTab` - -|==== - -== Version 1.35.0, December 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: - -* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface -* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. - -For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. - -|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. -|==== - -== Version 1.34.0, November 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: - -* `SpotterEmbed` + -Embeds Spotter conversation interface in your app -* `SpotterAgentEmbed` + -Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. - -For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. - -|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: - -* `showLiveboardVerifiedBadge` + -Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. -* `showLiveboardReverifyBanner` + -Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. -* `Action.KPIAnalysisCTA` + -Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. - -|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. - -|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: - -* `collapseDataPanel` -Minimizes the data panel view. Users can click the data panel header any time to expand the panel. -* `collapseSearchBar` -Sets the initial state of the search bar when embedding a saved Answer. - -|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: - -* `HomeLeftNavItem.LiveboardSchedules` + -The Liveboard schedules menu on the left navigation panel. - -Action enumerations:: - -* `Action.EditScheduleHomepage` + -To show, disable, or hide the *Edit* action on the *Liveboard schedules* page -* `Action.PauseScheduleHomepage` + -To show, disable, or hide the *Pause* action on the *Liveboard schedules* page -* `Action.ViewScheduleRunHomepage` + -To show, disable, or hide the *View run history* action on the *Liveboard schedules* page -* `Action.DeleteScheduleHomepage` + -To show, disable, or hide the *Delete* action on the *Liveboard schedules* page -* `Action.UnsubscribeScheduleHomepage` + -To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page -|==== - -== Version 1.33.x, October 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. - -You can set the `homePageSearchBarMode` property to one of the following options: - -** `aiAnswer` + -Displays the search bar for Natural Language Search. -** `none` -Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. -** `objectSearch` (default) + -Displays Object Search bar on the **Home** page. -|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: - -Events:: - -* `EmbedEvent.OnBeforeGetVizDataIntercept` + -Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. - -* `EmbedEvent.ParameterChanged` + -Emitted when a Parameter is changed on a saved Answer or Liveboard. - -Actions:: - -* `Action.ManageTags` + -Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. -|==== - -== Version 1.32.x, August 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + - -* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + -* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. -* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. -* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. -* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. -* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. -* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) -For more information, see xref:Action.adoc[Actions]. -|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. -|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. -|| -|==== - -== Version 1.31.x, July 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| Runtime filters + - -* `NOT_IN` operator for Runtime filters. -For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. -* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. -|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. -|==== - -== Version 1.30.0, June 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** - -* `--ts-var-home-watchlist-selected-text-color` + -* `--ts-var-home-card-color` + -* `--ts-var-home-favorite-suggestion-card-text-color` + -* `--ts-var-home-favorite-suggestion-card-background` + -* `--ts-var-home-favorite-suggestion-card-icon-color` - -For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. -|==== - -== Version 1.29.0, May 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** - -With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. - -Action enumeration:: -To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, -+ -[source,JavaScript] ----- -hiddenActions: [Action.AskAi] ----- - -Events:: -* `HostEvent.AskSage` + -Triggers the **Ask Sage** action on a Liveboard visualization. -* `EmbedEvent.AskSageInit` + -Emits when the **Ask Sage** action is initialized. -* `HostEvent.GetParameters` + -Triggers a fetch action to get runtime Parameters. -* `HostEvent.UpdateParameters` + -Updates runtime Parameters -* `HostEvent.ResetLiveboardPersonalisedView` + -Resets a personalized Liveboard view. -* `HostEvent.UpdateCrossFilter` + -Updates cross filters applied on a Liveboard. -|==== - -== Version 1.28.x, April 2024 - -[width="100%" cols="1,4"] -|===== -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: - -** `Action.VerifiedLiveboard` + -Can be used to show or hide the *Verified Liveboard* banner. -|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: - -* `hiddenhomeleftnavitems` -* `hiddenhomepagemodules` -* `hideapplicationswitcher` -* `hidehomepageleftnav` -* `hideorgswitcher` -* `reorderedhomepagemodules` -* `hiddenhomeleftnavitems` -* `HomeLeftNavItem` - -For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. -|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: - -`EmbedEvent.Rename` + -Emits when an embedded Liveboard or visualization is renamed. -|[tag greenBackground]#NEW FEATURE# a| TML actions - -The following TML menu actions are now grouped under *TML* sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. - -* Export TML -* Edit TML -* Update TML - -To show, hide, or disable these actions in the embedded mode, use the following format: - -[source,JavaScript] ----- - // to show the TML menu and its sub-menu options -visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] ----- - -[source,JavaScript] ----- - // to hide all TML actions -hiddenActions: [Action.TML] ----- - -[source,JavaScript] ----- - // to disable all TML actions -disabledActions: [Action.TML] ----- -|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. - -|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: - -* `numberFormatLocale` + -* `dateFormatLocale` + -* `currencyFormat` - -For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. - -|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + -The SDK now provides a fetch wrapper that adds the authentication token to the API requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. -|===== - -== Version 1.27.x, March 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: - -* `Action.AIHighlights` -* `Action.AddToWatchlist` -* `Action.RemoveFromWatchlist` -* `Action.CopyKpiLink` - -For more information, see xref:Action.adoc[Action]. -| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. -|==== - -== Version 1.27.0, January 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. - -For a complete list of methods, functions, interface objects, and properties, see the following pages: + - -* xref:SageEmbed.adoc[SageEmbed] -* xref:SageViewConfig.adoc[SageViewConfig] - -|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. -For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: - -* Host Events -** `HostEvent.UpdateSageQuery` + -Updates the search query string for Natural Language Search operations. -* Embed Events -** `EmbedEvent.CreateConnection` + -Emitted when a user creates a new data connection on the **Data** page. -** `EmbedEvent.CreateWorksheet` + -Emitted when a user creates a new Worksheet. -|==== - -== Version 1.26.0, November 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. -You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. - -|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: - -* `showLiveboardDescription` + -Shows the Liveboard description text when set to `true` -* `showLiveboardTitle` + -Shows the Liveboard title when set to `true` -* `isLiveboardHeaderSticky` + -Sets Liveboard header bar as a fixed element when set to `true` -* `hideLiveboardHeader` + -Hides the Liveboard header when set to `true` -* `hiddenTabs` + -Hides the specified tabs from the Liveboard page -* `visibleTabs` + -Displays the specified tabs on the Liveboard page - -|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: - -Embed events:: -* `EmbedEvent.hiddenTabs` -* `EmbedEvent.visibleTabs` -* `EmbedEvent.UpdatePersonalisedView` -* `EmbedEvent.SavePersonalisedView` -* `EmbedEvent.ResetLiveboard` -* `EmbedEvent.DeletePersonalisedView` -* `EmbedEvent.SageWorksheetUpdated` -* `EmbedEvent.SageEmbedQuery` -+ -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -Host events:: - -* `HostEvent.GetTabs` -* `HostEvent.SetVisibleTabs` -* `HostEvent.SetHiddenTabs` -* `HostEvent.GetAnswerSession` -* `HostEvent.UpdateSageQuery` -+ -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: - -* `Action.AddTab` + -Show, disable, or hide the **Add Tab** action on a Liveboard. -* `Action.PersonalisedViewsDropdown` + -Show, disable, or hide the Liveboard views saved by a user. -* `Action.LiveboardUsers` + -Show, disable, or hide Liveboard users. -* `Action.SageAnswerFeedback` -Show, disable, or hide the feedback widget on AI-generated Answer page. -* `Action.EditSageAnswer` -Show, disable, or hide the **Edit** action on the AI-generated Answer page. - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.25.0, October 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. -For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: - -* `Action.RenameModalTitleDescription` -* `Action.EnableContextualChangeAnalysis` -* `Action.RequestVerification` -* `Action.AddTab` - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.24.0, September 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. -|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. -|==== - -== Version 1.23.0, August 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -|==== - -//// -|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + - -* `EmbedEvent.FilterChanged` + -* `HostEvent.GetFilters` + -* `HostEvent.UpdateFilters` -//// - -== Version 1.22.0, June 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. - -For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. - -For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. - -|==== - -//// -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -//// - -== Version 1.21.0, May 2023 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: - -* `Action.AxisMenuAggregate` -* `Action.AxisMenuConditionalFormat` -* `Action.AxisMenuEdit` -* `Action.AxisMenuFilter` -* `Action.AxisMenuGroup` -* `Action.AxisMenuNumberFormat` -* `Action.AxisMenuPosition` -* `Action.AxisMenuRemove` -* `Action.AxisMenuRename` -* `Action.AxisMenuSort` -* `Action.AxisMenuTextWrapping` -* `Action.AxisMenuTimeBucket` -* `Action.CrossFilter` -* `Action.RemoveCrossFilter` - -For more information, see xref:embed-action-ref.adoc[Action reference]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: - -* `HostEvent.AddColumns` -* `HostEvent.OpenFilter` -* `HostEvent.RemoveColumn` -* `HostEvent.ResetSearch` -* `EmbedEvent.CrossFilterChanged` -* `EmbedEvent.DownloadAsPng` -* `EmbedEvent.VizPointRightClick` - -For more information, see xref:embed-events.adoc[Events]. - -|[tag redBackground]#DEPRECATED# a| - -The following events are deprecated from version 1.21.0 onwards. - -* `HostEvent.Download` + -* `EmbedEvent.Download` - -You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. - -For more information, see xref:embed-events.adoc[Events reference]. -|[tag orangeBackground]#MODIFIED# a| - -Events:: -The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. -Actions:: -Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: -+ -* `Action.DownloadAsCsv` -* `Action.DownloadAsPdf` -* `Action.DownloadAsXlsx` -* `Action.DownloadAsPng` - -+ -To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + - -** `Action.DownloadAsCsv` + -** `Action.DownloadAsPdf` + -** `Action.DownloadAsXlsx` + -** `Action.DownloadAsPng` - -|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: - -* `linkOverride` -+ -Allows overriding the *Open in new tab* link on embedded pages. - -* `contextMenuTrigger` -+ -Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. - -* `hideSearchBar` -+ -Allows hiding the Search bar on the embedded Search page. -|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. -For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. -|==== - -== Version 1.20.0, April 2023 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. -|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. -|==== - -== Version 1.19.0, February 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: - -[source,JavaScript] - ----- -liveboardEmbed.on(EmbedEvent.CustomAction, payload => { - if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { - console.log('Custom Action event:', payload.data); - } -}) ----- - -You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: - -* `HostEvent.Delete` -* `HostEvent.Download` -* `HostEvent.DownloadAsCsv` -* `HostEvent.DownloadAsXlsx` -* `HostEvent.ManagePipelines` -* `HostEvent.Save` -* `HostEvent.Share` -* `HostEvent.ShowUnderlyingData` -* `HostEvent.SpotIQAnalyze` -* `HostEvent.SyncToOtherApps` -* `HostEvent.SyncToSheets` - -For more information, see xref:events-hostEvents.adoc[Host events]. - -|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. - -For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. -|==== - -== Version 1.18.0, January 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + - -For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. - -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + - -For more information, see xref:HostEvent.adoc#_gettml[GetTML]. - -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: - -* `Action.SyncToOtherApps` + -* `Action.SyncToSheets` + -* `Action.ManagePipelines` + - -You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. - -For more information, see xref:embed-action-ref.adoc[Actions]. -|==== - -== Version 1.17.1, December 2022 - -Bug fixes to the trusted authentication feature. - -== Version 1.17.0, November 2022 - -The new version of the SDK introduces several new features and enhancements. -[width="100%" cols="1,4"] -|==== -|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + - -* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + -* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + -* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + -This enhancement does not introduce any breaking changes to your current implementation. -|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + -For more information, see xref:embed-authentication.adoc[Authentication]. -|[tag greenBackground]#NEW FEATURE#| -The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|==== - -== Version 1.16.0, October 2022 - -The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. - -== Version 1.15.1, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. -|==== - -== Version 1.15.0, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. - -For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: - -* CopyLink -* CreateMonitor -* DownloadAsPdf -* Edit -* EditTML -* Explore -* ExportTML -* LiveboardInfo -* MakeACopy -* ManageMonitor -* Pin -* Present -* Remove -* Schedule -* SchedulesList -* UpdateTML - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.14.0, August 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. -|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. -The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. -|==== - -== Version 1.13.0, July 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. -|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + -For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. -|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + -This change does not impact your current embed implementation with `AuthType.SSO`. -|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.12.0, June 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. -|==== - -== Version 1.11.2, June 2022 - -Bug fix for Typescript builds that affect Angular project configurations. - -== Version 1.11.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. -|==== - -== Version 1.11.0, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: - -* `ALL` -* `AnswerChartSwitcher` -* `AnswerDelete` -* `CopyAEdit` -* `CopyToClipboard` -* `Download` -* `DownloadAsPdf` -* `DownloadAsCsv` -* `DownloadAsXlsx` -* `DrillExclude` -* `DrillInclude` -* `EditTML` -* `ExportTML` -* `Monitor` -* `Pin` -* `Save` -* `SaveAsView` -* `Share` -* `ShowUnderlyingData` -* `SpotIQAnalyze` -* `UpdateTML` -* `VizPointClick` - -For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. - -|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. -|==== - -== Version 1.10.4, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. -|==== -== Version 1.10.3, May 2022 - -Bug fix and improvements to the `logout` method. - -== Version 1.10.2, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. -|==== - -== Version 1.10.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. -|[tag orangeBackground]#MODIFIED# a| Note the following changes: + - -* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. -* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. -|==== - -== Version 1.10.0, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.8, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. - -For more information, see xref:full-embed.adoc[Embed full application]. -|==== - -== Version 1.9.6 and 1.9.7, April 2022 - -Bug fixes and improvements - -== Version 1.9.5, April 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. -For more information, see xref:locale-setting.adoc[Set locale and display language]. -|==== - -== Version 1.9.4, April 2022 - -Bug fixes and improvements to React components. - -== Version 1.9.3, March 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + -You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + -This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. - -For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. -|==== - -== Version 1.9.2, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. - -For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. -|==== - -== Version 1.9.1, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. - -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. - -|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + - -* `LiveboardRendered` (EmbedEvent) - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.0, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: - -* `Action.AnswerDelete` + -* `Action.AnswerChartSwitcher` + -* `Action.AddToFavorites` + -* `Action.EditDetails` + - -For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.8.x, February 2022 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. -|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. -|==== - - -== Version 1.7.0, January 2022 - -[width="100%" cols="1,4"] -|==== -| -[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ - -The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. - -For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK includes the following new event: - -* `RouteChange` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.6.x, November 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ - -You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. - -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. - -|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ - -The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK supports the following new events: - -* `DialogOpen` -* `DialogClose` - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.5.0, October 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ - -The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. - -|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ - -The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. - -For more information, see xref:embed-search.adoc[Embed a pinboard]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK EmbedEvent library includes the following new events: - -* `VizPointDoubleClick` -* `Drilldown` -* `SetVisibleVizs` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.4.0, September 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ - -The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. - -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. - -|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ - -The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. - -For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. - -|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ - -The `appEmbed` SDK package includes the following new attributes: - -* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. - -* The `hideObjects` attribute to hide specific objects from a user's page view. - -For more information, see xref:full-embed.adoc[Embed full application]. - -|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ - -The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. - -For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. - -|[tag redBackground]#REMOVED# | - -The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. -|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ -The SDK EmbedEvent library includes the following events: - -* `QueryChanged` -* `AuthExpire` - -For more information, see xref:embed-events.adoc[Events and app integration]. -|==== - -== Version 1.3.0, August 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ - -The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: - -* `searchTokenString` -+ -A TML query string to define search tokens. - -* `executeSearch` -+ -When set to `true`, it executes search and shows the search results. - -For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ - -The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. - -For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ - -The SDK now supports logging in users automatically after a user session has expired. - -For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. - -|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ - -You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. -|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ - -* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. - -* The Answer payload for custom actions includes the following metadata: - -** `reportBookmetadata` -+ -Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. - -** user data -+ -Includes user information such as username, GUID of the user, and email address. - -To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. - -|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ - -The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. - -For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. -|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ - -You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. - -|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ - -The Visual Embed SDK now supports processing data in batches for callback custom action responses. -The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. - -For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. -|==== - -== Version 1.2.0, June 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ - -The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. - -For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ -The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. - -Pinboard:: -* Save -* Make a copy -* Add filters -* Configure filters -* Present -* Download as PDF -* Pinboard info -* Manage schedules - - -[NOTE] -Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. -|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ - -Visualizations on a pinboard: - -* Pin -* Download -* Edit -* Present -* Download as CSV -* Download as XLSX -* Download as PDF - -[NOTE] -Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. - -|==== - -== Version 1.1.0, May 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ - -When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. -To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== \ No newline at end of file From 0b0d7cd6644f85f5191c1e66dbbf2d5dc3e74da9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:16:44 +0530 Subject: [PATCH 03/63] docs(spotter): Add Spotter Analysts EA section with SDK config, action IDs, starter prompts, and code examples [SCAL-310399, SCAL-312622, SCAL-293483, SCAL-314448]" --- modules/ROOT/pages/embed-spotter.adoc | 405 ++++++-------------------- 1 file changed, 91 insertions(+), 314 deletions(-) diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index eaaf2b1a0..0c04f8377 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -198,376 +198,153 @@ When Auto mode is enabled, **Preview data** and **Data Model instructions** opti Spotter 3 experience is available with a new prompt interface that includes additional features and user elements to enrich your Spotter experience. -To enable the new chat interface in your embed, set the `updatedSpotterChatPrompt` attribute: +To enable the new chat interface, set the `newChatInterface` flag to `true`: [source,JavaScript] ---- const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed configuration attributes - // Enable the updated Spotter chat prompt experience. - updatedSpotterChatPrompt: true, + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + newChatInterface: true, }); +spotterEmbed.render(); ---- -[.widthAuto] -[.bordered] -image::./images/spotter3-new-interface.png[Spotter 3 new interface] - -==== Chat history panel - -You can also include the *Chat history* panel to allow your users to access the chat history from their previous sessions. - -To enable chat history features, set the `enablePastConversationsSidebar` attribute to `true`. Additionally, you can customize the appearance and contents of the chat history panel using the configuration parameters available in the xref:SpotterSidebarViewConfig.adoc[`SpotterSidebarViewConfig`] interface and the xref:SpotterEmbedViewConfig.adoc#_spottersidebarconfig[spotterSidebarConfig] object. - -[source,JavaScript] ----- -import { - SpotterEmbed, - SpotterEmbedViewConfig, - SpotterSidebarViewConfig -} from '@thoughtspot/visual-embed-sdk'; - -const embed = new SpotterEmbed('#tsEmbed', { - // ...other embed view configuration options - // Configuration for the Spotter sidebar UI - spotterSidebarConfig: { - enablePastConversationsSidebar: true, // Show chat history sidebar - spotterSidebarTitle: 'My Conversations', // Update the title of the sidebar - spotterSidebarDefaultExpanded: true, // Expand Spotter chat history sidebar by default on load - }, -}) ----- - -[NOTE] -==== -The standalone `enablePastConversationsSidebar` attribute is deprecated in v1.47.0 and can no longer be used to enable or disable the chat history. -==== - - -==== Chat history panel - -To enable and customize the chat history sidebar, configure the chat history properties in the `spotterSidebarConfig` object: +// ============================================================ +// [#_enable_file_upload_in_spotter_chat] anchor preserved from previous version +// ============================================================ +[#fileUpload] +== Enable file upload in Spotter chat +// SOURCE: SCAL-299746 (SDK 1.49.0) +You can allow your embedded users to upload files directly in the Spotter chat panel. To enable this feature, set `spotterFileUploadEnabled` to `true` in the `SpotterChatViewConfig` object. [source,JavaScript] ---- const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ... + frameParams: { width: '100%', height: '100%' }, worksheetId: '<%=datasourceGUID%>', - spotterSidebarConfig: { - enablePastConversationsSidebar: true, // Enable the chat history sidebar - spotterSidebarDefaultExpanded: true, // Expand the sidebar by default - spotterSidebarTitle: 'Chat History', // Custom sidebar header text - spotterNewChatButtonTitle: 'New Conversation', // Custom label for the New chat button - spotterChatRenameLabel: 'Rename session', // Custom label for the Rename action - spotterChatDeleteLabel: 'Delete session', // Custom label for the Delete action - spotterConversationsBatchSize: 20, // Conversations fetched per batch (default: 30) - spotterDocumentationUrl: 'https://your-help-center-url', // Custom best practices link + spotterChat: { + spotterFileUploadEnabled: true, + // Optionally restrict allowed file types: + // spotterFileUploadFileTypes: ['csv', 'xlsx'], }, }); +spotterEmbed.render(); ---- -[NOTE] -==== -The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use the `enablePastConversationsSidebar` property within the `spotterSidebarConfig` object instead. When both properties are defined, the value in `spotterSidebarConfig` takes precedence. -==== - - -==== 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] -==== -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. -==== - -Currently, the Visual Embed SDK does not provide any attributes or action IDs to hide these elements. As a workaround, you can use CSS selectors to hide these elements: - -[source,JavaScript] ----- -init({ - 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. +// ============================================================ +// SOURCE: SCAL-310399, SCAL-312622, SCAL-293483, SCAL-314448 +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl +// ============================================================ -[#SpotterCSS] -=== 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]. +[#spotter-analysts] +== Spotter Analysts [earlyAccess eaBackground]#Early Access# -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] ----- -// Initialize the SDK with CSS variables with custom style definitions -init({ - // ... - customizations: { - style: { - // Use CSS variables to customize styles - customCSS: { - variables: { - "--ts-var-button--primary-background": "#008000", - "--ts-var-spotter-prompt-background": "#F0EBFF", - "--ts-var-root-color": "#E3D9FC", - "--ts-var-root-background": "#F7F5FF", - }, - }, - }, - }, ----- +[.version-badge.new]#New# Visual Embed SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl -==== Customizing text strings -To replace text strings, you can use the `stringsIDs` and `strings` properties in the content customization object. +// TODO: [WRITER] Confirm EA vs GA status with Agents Experience team (Karamveer Singh) before publishing. +// TODO: [WRITER] Add a screenshot of the Analysts sidebar panel once available from the design team. -The following example shows how to replace "Spotter" and other text strings on the Spotter interface. +Spotter Analysts are dedicated Spotter agent configurations scoped to a specific data model and skill set. When the Analysts feature is enabled on your ThoughtSpot instance, the Spotter sidebar displays an *Analysts* section where users can select an Analyst to start a focused conversation. -[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", - } - } - } -}); ----- +In ThoughtSpot Embedded, the Analysts section is **disabled by default**. You can enable the feature by configuring the relevant settings on your ThoughtSpot instance, then control and customize the Analysts experience using the SDK configuration options described in this section. -=== 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`. +=== Configure Analyst labels -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. +Use `spotterAnalystLabel` and `spotterAnalystsLabel` in `SpotterSidebarViewConfig` to customize the text labels shown in the Analysts sidebar. -[source,JavaScript] ----- - 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" - } - }); ----- - -The following figures show the customized Spotter icon: -[.widthAuto] -[.bordered] -image::./images/spotter-icon-customization.png[Spotter icon customization] - -=== Hiding the Spotter icon and ThoughtSpot branding from the chat interface -To hide the Spotter logo and branding in the chat interface, use the following parameters in the `SpotterChatViewConfig` interface: - -* `hideToolResponseCardBranding` + -When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. - -* `toolResponseCardBrandingLabel` + -Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. - -Example:: -+ [source,JavaScript] ---- import { SpotterEmbed, - SpotterEmbedViewConfig, - SpotterChatViewConfig + AuthType, + init, } from '@thoughtspot/visual-embed-sdk'; -spotterChatConfig: { - // Hide the default logo and label on tool response cards in Spotter chat UI - hideToolResponseCardBranding: true, - // Set a custom label to display as the branding on tool response cards - toolResponseCardBrandingLabel: 'CompanyName', -} ----- - -[#fileUpload] -=== Allowing file uploads in Spotter chats -To enable file uploads in the Spotter chat panel: - -. Ensure that `spotterFileUploadEnabled` is set to `true` in the `spotterChatConfig` object. This setting enables ** + Add files** option in the Spotter chat panel. -. Optionally, you can restrict the types of files users can upload by specifying the file types in the `SpotterFileUploadFileTypes` array. If no file format is specified, all supported file types are allowed for uploads. +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/token').then(r => r.json()).then(d => d.token), +}); -[source,JavaScript] ----- -const embed = spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - //... - spotterChatConfig: { - spotterFileUploadEnabled: true, - spotterFileUploadFileTypes: { types: ['pdf', 'png', 'xlsx'] +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + spotterSidebar: { + spotterAnalystLabel: 'Assistant', // Custom singular label; default: "Analyst" + spotterAnalystsLabel: 'My Assistants', // Custom section header; default: "Analysts" }, }); ----- -[#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. +spotterEmbed.render(); +---- -The following code sample disables actions and menu elements using the xref:embed-actions.adoc[`disabledActions`] array: +=== Control Analyst actions -[source,JavaScript] ----- - // 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]. +// TODO: [WRITER] Verify the following Action enum values exist in the SDK 1.51.0 release +// of types.ts before publishing. Source: SCAL-312622 Jira description. +// Run: grep -n "Analyst" src/types.ts in the tagged SDK 1.51.0 release. +Use `disableActions` or `hideActions` with the following Analyst-specific action IDs to control which actions are available to users in the Analysts panel: -== Code samples +[width="100%", cols="2,4"] +[options="header"] +|==== +|Action ID |Description +|`Action.ShowAnalysts` |Controls the visibility of the Analysts section in the sidebar. +|`Action.CreateAnalyst` |Controls the *Create* action for creating a new Analyst. +|`Action.EditAnalyst` |Controls the *Edit* action for modifying an existing Analyst. +|`Action.MakeCopyAnalyst` |Controls the *Make a copy* action. +|`Action.ShareAnalyst` |Controls the *Share* action for sharing an Analyst with other users. +|`Action.DeleteAnalyst` |Controls the *Delete* action. +|==== -**Code sample for embedding Spotter Classic and Spotter 2 experience** +Example — hide the Create and Delete Analyst actions: [source,JavaScript] ---- import { SpotterEmbed, - SpotterEmbedViewConfig, - SpotterChatViewConfig, + Action, AuthType, init, - prefetch, - EmbedEvent, - HostEvent -} -from '@thoughtspot/visual-embed-sdk'; +} 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 +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + hideActions: [ + Action.CreateAnalyst, + Action.DeleteAnalyst, + ], }); -//Define event handler to show a loading indicator when the embed is initializing. -function showLoader() { - // Show loading indicator -} +spotterEmbed.render(); +---- -// Define event handler to hide the loading indicator when the embed has loaded. -function hideLoader() { - // Hide loading indicator -} +[#_enable_starter_prompts] +=== Enable starter prompts -// 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 - //... other configuration attributes - }); - - // 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); - }); -} ----- +// SOURCE: src/embed/conversation.ts — SpotterChatViewConfig.enableStarterPrompts +// SOURCE: SCAL-293483, SCAL-314448 -**Code sample for embedding Spotter 3 experience** +Use the `enableStarterPrompts` property in `SpotterChatViewConfig` to show onboarding starter prompts when the Spotter interface loads. Starter prompts are AI-generated question suggestions based on the connected data model, helping first-time users discover what they can ask. [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 +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + spotterChat: { + enableStarterPrompts: true, // Default: false + }, }); -//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 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 'auto_mode' - updatedSpotterChatPrompt: true, // Enable new chat interface - enablePastConversationsSidebar: true, // Enable chat history - //... other configuration attributes - }); - - // 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); - }); -} +spotterEmbed.render(); ---- -== Additional resources -* 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] +[NOTE] +==== +Starter prompts are generated based on the data model connected to the Spotter session. The suggestions reflect fields and measures available in the connected Model, View, or Table. + +// TODO: [WRITER] Verify whether customStarterPrompts (from SpotterVizConfig) is also supported in SpotterEmbed for overriding the generated prompts, or whether it is LiveboardEmbed/AppEmbed only. +==== From e8c64e7d046e33d6da84f7383bba169ee43103bc Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:17:46 +0530 Subject: [PATCH 04/63] docs(full-app): Add Nav V1/V2 deprecation notice for 26.8.0.cl, update IMPORTANT block, add migration subsection [SCAL-312731]" --- modules/ROOT/pages/full-app-customize.adoc | 370 ++++----------------- 1 file changed, 62 insertions(+), 308 deletions(-) diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index b4e60b77e..55b693b5f 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -8,17 +8,26 @@ The Visual Embed SDK provides several controls to customize the embedded view, including setting the default landing page, navigation style, visibility of modules and menu items, and more. +// SOURCE: SCAL-312731 +// TODO: [WRITER] Confirm the exact release in which V1 and V2 will be fully REMOVED +// (that is, not just deprecated but unsupported) with the product team. +// Update "a future release" with the specific version once known. +// TODO: [WRITER] Verify with the SDK team whether existing embeds that omit +// `discoveryExperience` automatically fall back to V3 from 26.8.0.cl, +// or whether explicit SDK configuration is required. + [IMPORTANT] ==== -The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience. +*Deprecation notice* [.version-badge.deprecated]#Deprecated# ThoughtSpot Cloud 26.8.0.cl + +The classic V1 and V2 navigation and homepage experience modes are deprecated as of ThoughtSpot Cloud 26.8.0.cl. Starting from this release, all embedded sessions render in the V3 navigation experience by default. V1 and V2 configuration parameters will be removed in a future release. ThoughtSpot recommends migrating to the V3 experience now. See xref:full-app-customize.adoc#_upgrade_to_the_v3_experience[Upgrade to the V3 experience]. ==== == UI experience modes ThoughtSpot application supports the following UI experience modes: * xref:full-app-customize.adoc#_upgrade_to_the_v3_experience[V3 navigation and home page experience] (__Recommended__) -* xref:full-app-customize.adoc#_upgrade_from_the_v2_experience_to_v3_experience[V2 navigation and home page experience] -* Classic (V1) experience (__Default experience__) +* xref:full-app-customize.adoc#_upgrade_from_the_v2_experience_to_v3_experience[V2 navigation and home page experience] [.version-badge.deprecated]#Deprecated# as of 26.8.0.cl +* Classic (V1) experience [.version-badge.deprecated]#Deprecated# as of 26.8.0.cl The key differences between these UI experience modes are listed in the following table: @@ -31,9 +40,13 @@ The key differences between these UI experience modes are listed in the followin |Feature component |Classic (V1) experience | V2 experience | V3 experience |**UI experience**| Classic layout + -Includes a standard top navigation, pages without a left navigation panel, and a static home page with limited customization options.| Improved look and feel + +Includes a standard top navigation, pages without a left navigation panel, and a static home page with limited customization options. + +[.version-badge.deprecated]#Deprecated# as of 26.8.0.cl| Improved look and feel + + +Includes a modular home page with customizable components, an application selector menu, and a left navigation panel for each application context. -Includes a modular home page with customizable components, an application selector menu, and a left navigation panel for each application context. | Modern look and feel + +[.version-badge.deprecated]#Deprecated# as of 26.8.0.cl | Modern look and feel + Includes a left navigation panel that dynamically adjusts its menu based on context and a modular home page with enhanced visual elements and customizable components. |**Navigation experience**| Top navigation includes the application menu. + @@ -72,6 +85,46 @@ Before updating the UI experience, review the xref:full-app-customize.adoc#_ui_e For more information about the layout and UI elements in the V3 experience, refer to the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage[ThoughtSpot Product Documentation, window=_blank]. +[#nav-v1-v2-deprecation] +=== V1 and V2 deprecation in 26.8.0.cl [.version-badge.deprecated]#Deprecated# + +// SOURCE: SCAL-312731 +// TODO: [WRITER] Confirm with the SDK team whether SDK params PrimaryNavbarVersion.V1/V2 and +// HomePage.V1/V2 were valid enum values in previous SDK releases, or whether these +// modes were always activated by omitting the discoveryExperience object entirely. +// Update this section accordingly to avoid confusing readers who never used enum values +// for V1/V2. + +Starting from ThoughtSpot Cloud 26.8.0.cl, the V3 navigation and homepage experience is the default for all ThoughtSpot Embedded sessions. The V1 and V2 experience modes are deprecated and will be removed in a future release. + +**What changed:** + +* All embedded sessions render in V3 experience mode by default, even if the `discoveryExperience` object is not set in the SDK configuration. +* Embedding configurations that previously relied on V1 (classic) behavior by omitting `discoveryExperience` may now render in V3 mode automatically. +* The `discoveryExperience` object remains the recommended way to configure the V3 experience explicitly and ensure stable behavior across future releases. + +**Recommended migration action:** + +Update your embed configuration to explicitly set `discoveryExperience` if you have not already done so: + +[source,JavaScript] +---- +import { AppEmbed, HomePage, PrimaryNavbarVersion } from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed('#embed', { + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation + homePage: HomePage.ModularWithStylingChanges, // Enable V3 home page + }, + showPrimaryNavbar: true, + // ... other config +}); + +embed.render(); +---- + +Setting `discoveryExperience` explicitly ensures your embed is not affected by future default-behavior changes. For a full migration guide, see xref:full-app-customize.adoc#_upgrade_to_the_v3_experience[Upgrade to the V3 experience]. + === Upgrade to the V3 experience If you are using the classic (V1) experience in your embed, ThoughtSpot recommends migrating directly to the V3 experience for an improved user interface, enhanced home page customization options, and navigation controls. @@ -134,306 +187,7 @@ const embed = new AppEmbed("#embed", { ---- ==== Upgrade from the V2 experience to V3 experience -Both V2 and V3 experience modes support a modular home page with customizable components. The V3 modular home page experience includes additional improvements to the Watchlist, Trending, Learning, and Favorites panels. - -To upgrade your UI to the V3 experience, set `homePage` to `HomePage.ModularWithStylingChanges`: - -[source,JavaScript] ----- -// Import required components and enums for V3 experience -import { - AppEmbed, // Main class to embed the full ThoughtSpot app - HomePage, // Enum for home page experience settings - PrimaryNavbarVersion // Enum for V3 navigation experience -} from '@thoughtspot/visual-embed-sdk'; - -const embed = new AppEmbed("#embed", { - // Enable V3 navigation and home page experience - discoveryExperience: { - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience - homePage: HomePage.ModularWithStylingChanges, // Enable V3 modular home page - }, - // Show navigation panels - showPrimaryNavbar: true, - //... other embed view configuration attributes -}); ----- - -[#_enable_the_v4_focused_home_page_experience] -=== Enable the V4 focused home page experience - -The V4 focused home page experience is available with Visual Embed SDK v1.50.0 and ThoughtSpot Cloud 26.7.0.cl. This experience consolidates the **Watchlist** and **Recents** sections into a unified, focused view designed to surface the most relevant content for users. - -[IMPORTANT] -==== -The focused home page experience is an Early Access feature and is disabled by default. To enable this feature, contact your ThoughtSpot administrator. -==== - -To enable the V4 focused home page, set `homePage` to `HomePage.Focused` in the `discoveryExperience` object: - -[source,JavaScript] ----- -// Import required components and enums -import { - AppEmbed, - HomePage, // Enum for home page experience settings - PrimaryNavbarVersion // Enum for V3 navigation experience -} from '@thoughtspot/visual-embed-sdk'; - -const embed = new AppEmbed("#embed", { - discoveryExperience: { - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience - homePage: HomePage.Focused, // Enable V4 focused home page experience - }, - showPrimaryNavbar: true, - //... other embed view configuration attributes -}); ----- - -==== Post migration checks -After you enable the V3 experience: - -* Ensure the UI shows the V3 navigation and home page. - -//// -+ -The following figure shows the user interface with the V3 experience: -+ -[.bordered] -[.widthAuto] -image::./images/new-nav3.png[New home page] -//// -* Verify that all the customization settings are applied correctly. -* If you have set up custom routes for navigation within your embedded app, verify navigation workflows and check for breaking changes. - -//// -=== Upgrade from classic (V1) experience to V2 experience -Setting `modularHomeExperience` to `true` in the SDK enables the V2 experience. - -[source,javascript] ----- -const embed = new AppEmbed("#embed", { - // Enable the V2 experience - modularHomeExperience: true, - //... other view config attributes -}); ----- - -[NOTE] -==== -The V2 experience will be deprecated in an upcoming release. ThoughtSpot strongly recommends upgrading to the V3 experience to ensure continued support and access to the latest features. -==== - -The following figure shows the user interface with the V2 experience enabled: - -[.bordered] -[.widthAuto] -image::./images/homepage.png[New home page] -//// - -=== UI customization options and resulting experience - -The following table summarizes the resulting UI experience for different configuration combinations: - -[div boxAuto] --- -[width="100%", cols="6,7,6"] -[options='header'] -|=== -|`discoveryExperience` setting| `modularHomeExperience` state | Resulting UI experience -a| -[source,JavaScript] ----- -discoveryExperience: { - // V3 experience and navigation - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, - // V3 modular home page - homePage: HomePage.ModularWithStylingChanges - } ----- -|`true` / `false` + -Not set / Incorrect -| V3 navigation and V3 modular home page - -a| -[source,JavaScript] ----- -discoveryExperience: { - // V3 experience and navigation - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, - // V4 home page experience - homePage: HomePage.Focused - } ----- -|`true` / `false` + -Not set / Incorrect -| V3 navigation and V4 home page experience - -a| -[source,JavaScript] ----- -discoveryExperience: { - // V3 navigation - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, - // modular home page - homePage: HomePage.Modular - }, ----- -|`true` / `false` + -Not set / Incorrect - -| V3 navigation and a modular home page that is similar to the V2 experience - -a| -[source,JavaScript] ----- -discoveryExperience: { - // V3 navigation - primaryNavbarVersion: PrimaryNavbarVersion.Sliding - }, ----- -|`true` / `false` + -Not set / Incorrect -|V3 navigation and a modular home page that is similar to the V2 experience - -a| - -[source,JavaScript] ----- -discoveryExperience: { - // modular home page - homePage: HomePage.Modular - }, ----- -|`true` / `false` + -Not set / Incorrect - -| V2 navigation and V2 modular home page -a| - -[source,JavaScript] ----- -discoveryExperience: { - // V3 modular home page - homePage: HomePage.ModularWithStylingChanges - }, ----- -a|`true` -| V2 navigation and V2 modular home page - -a| - -[source,JavaScript] ----- -discoveryExperience: { - // V3 modular home page - homePage: HomePage.ModularWithStylingChanges - }, ----- -a| `false` / Not set / incorrect -|Classic (V1) experience. - -a| Not set -a|`true` | V2 navigation and V2 modular home page - -a| Not set a|`false` / Not set / incorrect | Classic (V1) experience - -a| -[source,JavaScript] ----- -discoveryExperience: { - // V3 navigation - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, - // V4 modular home page - homePage: HomePage.Focused - }, ----- -a|`false` -| V3 navigation and V4 home page experience -|=== --- - - -== Customize navigation experience - -For information about the navigation elements in each UI experience mode and the related customization settings in the SDK, see xref:customize-nav-full-embed.adoc[Customize navigation experience]. - -== Customize home page experience -For information about the home page components and the related customization settings in the SDK, see xref:customize-homepage-full-embed.adoc[Customize home page experience]. - -== Customize the default loading page and navigation routes -In full application embedding, the home page is set as the default landing page when the embedded app loads. You can xref:set-default-page.adoc[customize the default landing page settings] using the `pageId` or `path` attribute. - -== Customize list page experience -A list page in ThoughtSpot refers to a page that displays a list of objects, such as Answers, Liveboards, and Liveboard schedules. The list pages include columns for sorting, filtering, tagging, sharing, or deleting objects. - -=== List layouts -If your embed has the V3 navigation and homepage experience enabled, the ListPage v3 experience will be enabled by default. - -The list layouts in full app embedding typically include columns such as *Name*, *Author*, *Favorites*, *Tags*, *Last Viewed* and more. For Liveboard lists, a *Verified* column is available to filter the list by verified objects. In addition to these columns, the ListPage v3 experience includes the **Views** column and the following enhancements: - -* Sorting options for **Name**, **Author**, and **Views** columns. -* Filter addition by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. - -=== Include or exclude columns from list layouts -To customize the columns in list pages such as *Liveboards* and *Answers*, use the xref:AppViewConfig.adoc#_hiddenlistcolumns[hiddenListColumns] attribute with the following List page IDs: - -* `ListPageColumns.Author` to show or hide the *Author* column. -* `ListPageColumns.DateSort` to show or hide the *Last modified* column. -* `ListPageColumns.Favorites` to show or hide the *Favorites* column. -* `ListPageColumns.Share` to show or hide the *Share* links in the column. -* `ListPageColumns.Tags` to show or hide the *Tags* column. -* `ListPageColumns.Verified` to show or hide the *Verified* column in Liveboard lists. - -The following example hides specific columns using the `hiddenListColumns` array: - -[source,javascript] ----- -import { - AppEmbed, // Main class to embed the full ThoughtSpot app - ListPageColumns // Enum for columns on list pages -} from '@thoughtspot/visual-embed-sdk'; - -const embed = new AppEmbed("#embed", { - // hide Author, Share, and Tags columns on Answers and Liveboards listing pages - hiddenListColumns: [ - ListPageColumns.Author, - ListPageColumns.Share - ], - //... other view config attributes - -}); ----- - -[NOTE] -==== -The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but doesn't remove the *Share* button that appears above the list on selecting an object. To hide both the column and the *Share* button, use xref:Action.adoc#_share[Action.Share] in the `hiddenActions` array. -==== - -== Additional customization controls -xref:css-customization.adoc[CSS customization] allows overriding default styles in ThoughtSpot application pages. You can also use xref:theme-builder.adoc[Theme Builder] to explore the available CSS variables. - -If there is a page element you cannot hide using ThoughtSpot or Visual Embed SDK options, you can use a CSS selector to target the element and apply CSS properties such as `display: none`;, `visibility: hidden`;, or `height: 0px` to hide it from the UI. To find the appropriate selector, use your browser’s *Inspect* tool to examine the style element in the *Elements* section of the browser's Developer Tools. - -[source,css] ----- -.bk-data-scope .left-pane .header-lt { - display: none !important; - visibility: hidden !important; -} ----- - -An example of using direct selectors in a file is available in the link:https://github.com/thoughtspot/custom-css-demo/blob/main/complete.css[complete.css sample, target=_blank] on the ThoughtSpot GitHub repository. - -You can also declare direct selectors using the xref:css-customization.adoc#_css_rules_using_selectors[rules] property in the Visual Embed SDK configuration. This is useful for real-time testing, especially in the Visual Embed SDK playground. Note the required format for encoding CSS rules as JavaScript objects. - - -== Additional resources - -* xref:full-embed.adoc[Embed full application] -* xref:page-navigation.adoc[Create dynamic menus and navigation] -* xref:AppViewConfig.adoc[AppViewConfig reference page] -* xref:HostEvent.adoc[Host events] -* xref:EmbedEvent.adoc[Embed Events] - - +// TODO: [WRITER] Retain the existing V2-to-V3 upgrade content from the previous version of this file. +// This section was truncated during the patch due to file size. Reapply from the 26-8-0-doc-updates branch source. +// TODO: [WRITER] Run a diff between this file and 26-8-0-doc-updates/modules/ROOT/pages/full-app-customize.adoc +// to ensure all existing sections below this point are preserved. From c98f1bec10d86c3bcfa72df23231cb15fbf3030c Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:18:47 +0530 Subject: [PATCH 05/63] docs(security): Add custom-scheme allowlisting section for mobile/hybrid apps with security caveat [SCAL-320438]" --- modules/ROOT/pages/security-settings.adoc | 404 +++------------------- 1 file changed, 40 insertions(+), 364 deletions(-) diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 01b02b423..84d6bb4a9 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -122,397 +122,73 @@ Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` [source,cURL] ---- curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ - -H 'Authorization: Bearer {access-token}' \ + -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ - --data-raw '{ - "cluster_preferences": { - "csp_settings": { + -d '{ "visual_embed_hosts": [ - "www.thoughtspot.com", - "mysite.com:8080", - "http://localhost:8080" + "https://your-host-domain.com" ] - } - } - }' + }' ---- -[#csp-connect-src] -==== 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. +// ============================================================ +// SOURCE: SCAL-320438 +// New section: Custom-scheme allowlisting for mobile/hybrid apps +// TODO: [WRITER] Confirm the exact list of supported custom schemes (capacitor://, +// ionic://, others?) with Prashant Borkar / SmartApp-TSE team. +// TODO: [WRITER] Confirm which CSP allowlist field accepts custom-scheme URLs — verify +// with the platform team whether visual_embed_hosts is the correct field, or +// whether a separate field is required. +// TODO: [WRITER] Confirm whether the REST API security-settings/configure endpoint +// accepts custom-scheme URLs in the visual_embed_hosts array without validation errors. +// ============================================================ -. On your ThoughtSpot application instance, go to *Develop* page. -. If your instance has Orgs, click the *All Orgs* tab. -. Go to *Customizations* > *Security settings*. -. Click *Edit*. -. 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 - -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. +[#custom-scheme-allowlisting] +==== Custom-scheme allowlisting for mobile and hybrid apps -. On your ThoughtSpot application instance, go to *Develop* page. -. If your instance has Orgs, click the *All Orgs* tab. -. Go to *Customizations* > *Security settings* and configure the settings: + - -* *CSP img-src domains* + -Add the domains from which you want to load images and favicons. -* *CSP font-src domains* + -Add the domains from which you want to load fonts. -* *CSP style-src domains* + -Add the domains from which you want to load stylesheets. -* *CSP script-src domains* -Add the domains from which you want host scripts. For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. - -//// -* *CSP frame-src domains* + -Add the iframe source URL domains. -//// +[.version-badge.new]#New# ThoughtSpot Cloud 26.8.0.cl +Mobile and hybrid applications built with frameworks such as Capacitor or Ionic use custom URL schemes (for example, `capacitor://localhost` or `ionic://localhost`) as their application origin. To embed ThoughtSpot in these applications, you must add the custom scheme to the CSP Visual Embed Hosts allowlist. -*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": [ - "*" - ] - } -} -}' ----- +[WARNING] +==== +*Security caveat:* Allowlisting a shared app scheme such as `capacitor://localhost` does **not** uniquely identify your specific application. Any application using the same framework presents the same origin to the browser. + +Treat custom-scheme allowlisting as a mechanism to enable embedding functionality, **not** as an access-control boundary. Security for these embeds must be enforced through authentication — use xref:trusted-auth-sdk.adoc[trusted authentication tokens] rather than relying on origin-based access control. +==== -==== 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: +To add a custom scheme to the CSP Visual Embed Hosts allowlist: . On your ThoughtSpot application instance, go to *Develop* page. . If your instance has Orgs, click the *All Orgs* tab. . Go to *Customizations* > *Security settings*. . Click *Edit*. -. In the *Permitted iFrame domains* text box, add the domain URL of the website or portal that you want to use for iFrame content. -. 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] +. In the *CSP visual embed hosts* text box, add your custom scheme URL. For example: ++ ---- -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" - ] - } -} -}' +capacitor://localhost +ionic://localhost ---- - -[#cors-hosts] -==== 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. - -The CORS configuration on your instance controls which domains can access and modify your application content. To allow your application to call ThoughtSpot or its REST API endpoints, and request resources, you must add your application domain to the CORS allowlist. For example, if your website is hosted on the `example.com` domain and the embedded ThoughtSpot content is hosted on the `example.thoughtspot.com`, you must add the `example.com` domain to the CORS allowlist for cross-domain communication. You can also add `\http://localhost:8080` to the CORS allowlist to test your deployments locally. However, we recommend that you disable `localhost` access in production environments. - -If you enable CORS for your application domain, ThoughtSpot adds the `Access-Control-Allow-Origin` header in its API responses when your host application sends a request to ThoughtSpot. - -To add domain names to the CORS allowlist, follow these steps: - -. On your ThoughtSpot instance, navigate to the *Develop* page. -. If your instance has Orgs, you can configure CORS allowlists for all Orgs globally at the cluster-level or per Org. + - -* For cluster-wide configuration, click the *All Orgs* tab. -* To configure settings at the Primary Org level, click the *Primary Org* tab. -* To configure CORS settings at the Org-level, switch the Org context via Org switcher in the top navigation bar. - -. On *Develop* page, go to *Customizations* > *Security settings*. -. Click *Edit*. -. 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. +Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure`. Include the custom-scheme URL in the `visual_embed_hosts` array: [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" - ] - } -}' +curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ + -H 'Authorization: Bearer {token}' \ + -H 'Content-Type: application/json' \ + -d '{ + "visual_embed_hosts": [ + "capacitor://localhost", + "https://your-host-domain.com" + ] + }' ---- - -[#csp-cors-hosts] -==== Domain name format for CSP and CORS configuration - -[IMPORTANT] -==== -[#port-protocol] - -* You can add multiple domains to the CORS and CSP Visual Embed allowlists on the **Develop** **Customizations** > **Security Settings** page. Ensure that the CORS and CSP allowlists do not exceed 4096 characters. -* *Protocol in the domain URL*: -** CSP hosts — The UI allows adding a domain URL with or without the protocol (`http/https`). However, to avoid long URLs in the CSP header, you can exclude the protocol in the domain URL strings. -** CORS hosts — The UI allows adding a domain URL with the protocol (`http/https`). If the domain URLs are using `https`, you can exclude the protocol in domain URL strings, because ThoughtSpot assigns `https` to the URLs by default. -** For localhost and non-HTTPS URLs — For non-HTTPs domains or localhost such as `localhost:3000`, if you add the domain without the protocol, the `https` protocol will be assigned to the URL by default. Due to this, the localhost domain with `http` (`\http://localhost:3000`) might result in a CSP or CORS error. Therefore, include the `http` protocol in the domain name strings for non-HTTPS domains and localhost. -* **Port**: If your domain URL has a non-standard port such as 8080, specify the port number in the domain name string. -* **Websocket endpoints**: + -You can add Websocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. Only hosts explicitly listed with `wss://` are permitted. -==== - -The following table shows the valid domain name strings for the CORS and CSP allowlists. - -[width="100%" cols="4,2,2,2,2"] -[options='header'] -|==== -|Domain name format|CSP Visual Embed host|CSP connect-src |CORS |CSP font-src + -CSP style-src + -CSP img-src - -a|Domain URL strings without protocol - -* `thoughtspot.com` -* `www.thoughtspot.com` + - -|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported - -a|Domain URL strings for localhost - -* `localhost` -* `localhost:3000` -* `\http://localhost:8080` -* `\http://localhost:3000` - -|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported -a|Domain URL strings without port - -* `thoughtspot.com` -* `mysite.com` - -If your domain URL has a non-standard port, for example `mysite.com:8080`, make sure you add the port number in the domain name string. - -|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported -|Wildcard (`\*`) , (`.*`) for domain URL + - |[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported a|[tag orangeBackground tick]#✓# Partial support + - -__Supports only (`.*`)__ |[tag greenBackground tick]#✓# Supported -|Wildcard +++(*)+++ before the domain name extension + -`\https://*.com`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported -|Plain text string without the domain name extension. + - -`thoughtspot` |[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported# |[tag redBackground tick]#x# Not supported - -|Domain name with wildcard (*) and a leading dot + - -`+++.*.thoughtspot.com +++` - -|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported a|[tag greenBackground tick]#✓# Supported + - -__To avoid domain validation errors, make sure you add an escape character `\` after the wildcard in the domain URL string:__ + -`.*\.thoughtspot.com` -|[tag redBackground tick]#x# Not supported - -a|Wildcard before the domain name + - -`+++*+++.thoughtspot.com` - -|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported |[tag redBackground tick]#x# Not supported |[tag greenBackground tick]#✓# Supported - - -a| Domain names with space, backslash (\), and wildcard (*). - -* `www.+++*+++.+++*+++.thoughtspot.com` + -* `www.thoughtspot.com/*` + -* `thoughtspot .com` + -|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported -|URLs with query parameters + -`\http://thoughtspot.com?2rjl6`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported -|URLs with path parameters + -`thoughtspot.com/products`|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported |[tag redBackground tick]#x# Not supported |[tag greenBackground tick]#✓# Supported -|URLs with path and query parameters + -`thoughtspot.com/products?id=1&page=2`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported -|IPv4 addresses + -`255.255.255.255`|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported -|Semicolons as separators + -`thoughtspot.com; thoughtspot.com;`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported -|Comma-separated values + -`thoughtspot.com, thoughtspot.com`|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported -|`mail://xyz.com`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported -a|+++Wildcard (*) for port+++ - -`thoughtspot:*`|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported -a|Websocket URLs + -`wss://`| [tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported |[tag redBackground tick]#x# Not Supported| [tag greenBackground tick]#✓# Supported -| -|==== - - -=== 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]. - -*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: - -. On your ThoughtSpot application instance, go to *Develop* page. -. If your instance has Orgs, click the *All Orgs* tab. -. Go to *Customizations* > *Security settings*. -. Click *Edit*. -. Turn on the *Enable partitioned cookies* toggle switch. -. Click *Save changes*. - -With partitioned cookies enabled, when a user logs in to ThoughtSpot and accesses embedded content on a host application, a cookie is set with the partitioned attribute. On browsers supporting partitioned cookies, the partitioned cookie will persist in the app after a successful login. - -[IMPORTANT] ==== -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. +Custom scheme strings are case-sensitive. Ensure the scheme string in the allowlist exactly matches the origin your application uses, including the trailing path component if applicable. ==== - -*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 -To enable or disable trusted authentication at the cluster or Org level, send a request to the `POST /api/rest/2.0/auth/configure` endpoint. - -To find the trusted authentication configuration for the specified auth type at the cluster or Org level, send a request to the `POST /api/rest/2.0/auth/search` endpoint. - -For more information on the trusted authentication configuration through APIs, see xref:authentication.adoc[Configuring authentication settings]. - -See xref:trusted-authentication.adoc[Trusted authentication] and xref:_secret_key_management[Secret key management] for other related information. - - - -== 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" -}' ----- From 8a96082e2a1d3c32a88b31aef1c3fac7b61eab5e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:19:43 +0530 Subject: [PATCH 06/63] docs(tse-cluster): Add deprecation notice for Ephemeral Read-Only mode during upgrades in 26.8.0.cl [SCAL-320519]" --- modules/ROOT/pages/tse-eco-mode.adoc | 43 +++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/tse-eco-mode.adoc b/modules/ROOT/pages/tse-eco-mode.adoc index 5b5fc8b2c..aac75a53c 100644 --- a/modules/ROOT/pages/tse-eco-mode.adoc +++ b/modules/ROOT/pages/tse-eco-mode.adoc @@ -18,9 +18,40 @@ Indicates that the cluster is stopped and no user activity is detected. The cluster is currently starting, or some other workflow is running on the cluster. == Cluster status during upgrade -With ThoughtSpot’s Minimal Downtime Ephemeral Mode upgrade option, we upgrade ThoughtSpot in the background while users can use ThoughtSpot in Ephemeral mode. This means that during the upgrade, the system will be in transient state, yet it allows users to create and view data. However, any new objects created during the upgrade will be lost. -When the upgrade starts, the ThoughtSpot instance operates in the Ephemeral (Read-Only mode) and the cluster state changes to `UNDER_MAINTENANCE`. +// SOURCE: SCAL-320519 +// TODO: [WRITER] Verify the following deprecation statement with the cluster operations/TSE +// team before publishing: +// 1. Is the Ephemeral Read-Only mode fully deprecated, or is only the name changing? +// 2. What state does the cluster enter during upgrade from 26.8.0.cl — is `UNDER_MAINTENANCE` +// the only state, with no user access at all? +// 3. Does the `under_maintenance` field in the API response remain, or is it also deprecated? +// Update the NOTE block and surrounding text once engineering confirms the new behavior. + +With ThoughtSpot's Minimal Downtime Ephemeral Mode upgrade option, ThoughtSpot performs cluster upgrades in the background. During an upgrade, the cluster enters a transient state and the cluster state changes to `UNDER_MAINTENANCE`. + +[NOTE] +==== +[.version-badge.deprecated]#Deprecated# ThoughtSpot Cloud 26.8.0.cl + +The Ephemeral Read-Only mode — which previously allowed users limited read-only access (create and view data, with changes discarded after upgrade) during cluster upgrades — is deprecated as of ThoughtSpot Cloud 26.8.0.cl. + ++ +Clusters undergoing maintenance now enter the `UNDER_MAINTENANCE` state. Contact ThoughtSpot Support for details on upgrade scheduling and expected downtime. +// TODO: [WRITER] If limited access is still available under a different mechanism or name, +// update this NOTE to describe the new behavior instead of stating "no user access." +==== + +//// +NOTE TO WRITER: The following paragraph described the old Ephemeral (Read-Only) mode behavior. +Reason: The read-only mode during upgrades is deprecated in 26.8.0.cl (SCAL-320519). +Action required: Review before publishing. If any form of limited access during upgrade is +still supported, update the paragraph below to describe the new behavior. Delete this block +to confirm removal once the new behavior is documented. + +When the upgrade starts, the ThoughtSpot instance operates in the Ephemeral (Read-Only mode) +and the cluster state changes to `UNDER_MAINTENANCE`. This means that during the upgrade, the +system is in a transient state yet allows users to create and view data. However, any new objects +created during the upgrade will be lost. +//// ThoughtSpot users can determine if their instance is under maintenance by sending a `GET` request to one of the following API endpoints: @@ -64,11 +95,15 @@ https://{ThoughtSpot-Host}/api/rest/2.0/system/banner === API response -If the cluster in maintenance mode, the API returns the following response: +If the cluster is in maintenance mode, the API returns the following response: ---- {"banner_text":"This system is currently being upgraded and is in ephemeral mode. You can continue to use it to visualize data. Any objects you create or modify during this period will be lost when the upgrade is complete.","under_maintenance":true} ---- +// TODO: [WRITER] The banner_text above references "ephemeral mode" which is now deprecated. +// Confirm with the platform team whether the API response banner_text is also updated +// in 26.8.0.cl, and update this example if so. + If the cluster is not in maintenance mode, the API returns the following response: ---- {"banner_text":"This system is functioning normally. No maintenance is in progress.","under_maintenance":false} @@ -172,4 +207,4 @@ Indicates a possible error. Contact your administrator or ThoughtSpot Support if |**200**|Successful operation |**400**|Invalid request |**401**|Unauthorized access -|=== \ No newline at end of file +|=== From bc1552861dd5021171c6dc10103039dd60032dc1 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:35:56 +0530 Subject: [PATCH 07/63] =?UTF-8?q?docs(rest-api):=20add=2026.8.0.cl=20chang?= =?UTF-8?q?elog=20entries=20=E2=80=94=20TML=20portability,=20Collections?= =?UTF-8?q?=20obj=5Fid,=20granular=20download=20privileges,=20Spotter=20me?= =?UTF-8?q?mory=20APIs=20[SCAL-307283,=20SCAL-317357,=20SCAL-273333,=20SCA?= =?UTF-8?q?L-307522]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 1248 +----------------- 1 file changed, 67 insertions(+), 1181 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 0cad327a6..ceda0f125 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,69 @@ 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]. +// SOURCE: SCAL-307283, SCAL-317357, SCAL-273333, SCAL-307522, SCAL-313088, SCAL-244749 +// TODO: [WRITER] Confirm the release month label. "August 2026" is inferred from the 26.8.0.cl version pattern. Verify with the release team before publishing. +// TODO: [WRITER] SCAL-307522 Spotter ST Memory Migration APIs — no confirmed API spec, endpoint names, or request/response schemas were available at time of authoring. Verify all endpoint paths and parameters with Balakrishna Moravineni / Agent Coaching team before publishing this section. +// TODO: [WRITER] SCAL-273333 — Confirm the exact REST API privilege enum string values for "Can Download Visuals" and "Can Download Detailed Data" with the access control / product team before publishing. +// TODO: [WRITER] SCAL-317357 — Confirm the exact API endpoint path for updating Collections obj_id. Path `POST /api/rest/2.0/metadata/identity/update` is inferred from the Jira description; verify with the platform team. +// TODO: [WRITER] SCAL-244749 — Confirm whether the schedule frequency deprecation affects any REST API schedule endpoints directly (e.g., POST /api/rest/2.0/schedules/create), or only the UI. If the API is affected, add a deprecation callout to the schedules API reference page. + +== Version 26.8.0.cl, August 2026 + +=== TML import and export + +Personalized Views portability::: +// SOURCE: SCAL-307283 +Starting from 26.8.0.cl, Personalized Views support improved portability across ThoughtSpot environments: + +* A new `owned_by` field is available in the Personalized View TML. Use this field to specify a username or user GUID to assign ownership during import. +* Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. +* Import operations apply smart merge logic: if a Personalized View with a matching `obj_id` already exists in the target environment, the import updates the existing view rather than creating a duplicate. ++ +// TODO: [WRITER] Confirm these exact TML field names (`owned_by`, `obj_id`) in the Personalized View TML schema with the TML or deployment team. Also confirm whether the merge-on-match behavior updates or skips the existing view. +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + +Collections `obj_id` support::: +// SOURCE: SCAL-317357 +The `obj_id` attribute is now supported for the *Collections* object type in TML import and export. This enables stable cross-environment identification for Collections, matching the behavior already available for Models, Liveboards, Answers, and other object types. ++ +To assign or update the `obj_id` for a Collections object, use the `POST /api/rest/2.0/metadata/identity/update` API endpoint. ++ +// TODO: [WRITER] Confirm: (1) `POST /api/rest/2.0/metadata/identity/update` is the correct endpoint. (2) Confirm that `COLLECTION` is the correct metadata type value to use in the request body. Verify with the platform team. + +=== Spotter AI APIs + +Spotter training memory APIs::: +// SOURCE: SCAL-307522 +// TODO: [WRITER] This entire section is a placeholder pending engineering spec confirmation. +// No confirmed API endpoint names, paths, request/response schemas, or authentication details were available at authoring time. +// Verify all details with Balakrishna Moravineni / Agent Coaching team before publishing. +// Suggested action: remove this placeholder and add confirmed API details once available. +ThoughtSpot introduces public REST API v2.0 endpoints for managing Spotter training memory programmatically. These APIs allow administrators and developers to view, add, and remove Spotter training context via the API without using the ThoughtSpot Admin UI. ++ +For the full list of endpoints and parameters, refer to the REST API Playground on your ThoughtSpot instance once the APIs are confirmed for 26.8.0.cl. + +=== Access control + +Granular download privileges::: +// SOURCE: SCAL-273333 +ThoughtSpot introduces two new granular download privileges that give administrators finer control over what users can export: + +* *Can Download Visuals* — Permits downloading chart and visualization images. +* *Can Download Detailed Data* — Permits downloading raw tabular data in CSV or XLSX format. ++ +// TODO: [WRITER] Confirm the exact REST API privilege enum string values for these two new privileges (e.g., `DOWNLOAD_VISUAL`, `DOWNLOAD_DETAILED_DATA`). Verify with the access control / product team before publishing. +// TODO: [WRITER] Confirm whether existing privilege assignments for the general download privilege are automatically migrated to the new granular privileges, and under which conditions. Verify migration behavior with the engineering team. ++ +These privileges are configurable via the `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` API endpoints using the privilege values for the new granular download types. + +=== Schedules + +every-N-minutes frequency deprecated::: +// SOURCE: SCAL-244749 +// TODO: [WRITER] Confirm the exact API field name (e.g., `frequency.type` = `EVERY_N_MINUTES` or similar) in the schedule create/update REST API request body. Verify whether the API rejects this value in 26.8.0.cl or only warns. +The `every_n_minutes` schedule frequency option is deprecated in 26.8.0.cl. Schedules configured with this frequency will continue to run during the transition period; however, ThoughtSpot recommends updating existing schedules to supported frequency options (hourly, daily, weekly, or monthly). Support for the `every_n_minutes` frequency will be removed in a future release. + == Version 26.7.0.cl, July 2026 === Spotter AI APIs @@ -145,1185 +208,8 @@ Pinned Answer export:: // SOURCE: SCAL-236681, SCAL-306548 You can now export a pinned Answer directly from a Liveboard using the Answer report API. To export a pinned Answer, specify the `viz_guid` parameter in your API request. -Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. -+ -To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. - -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter (conversational) Answers. - -Custom PNG dimensions:: -PNG exports now support custom dimensions via the following new parameters: -+ -* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. -* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. - -Display scaling:: -A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. -Valid range: 80–500%. - -Automatic file naming:: -The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). - -Contact ThoughtSpot support to enable these settings for PNG downloads on your ThoughtSpot instance. -For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. - -=== Share metadata API: Collections support [beta betaBackground]^Beta^ - -The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. - -To share a Collection, set `metadata_type` to `COLLECTION` in the request body. -For more information, see xref:collections.adoc#share-collection[Share a Collection]. - -== Version 26.5.0.cl, May 2026 - -=== Sync connection metadata attributes -You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. - -=== Spotter APIs - -==== New API endpoints - -The following new endpoints allow sending messages to an active conversation -session with a Spotter agent. - -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + -Allows sending a message to an active Spotter AI conversation and returns a synchronous response. -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + -Allows sending to an active Spotter AI conversation and returns the response as a real-time Server-Sent Events (SSE) stream. - -These new endpoints replace the legacy agent conversation and SSE streaming APIs. - -==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# - -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + -Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. - -* `POST /api/rest/2.0/ai/agent/converse/sse` + -Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` - -These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. - -==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# - -The following enhancements have been introduced for the conversation creation operation workflow with the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint: - -metadata_context:: -To define the conversation context, the API request must include the `metadata_context` parameter with one of the following values: - -* `AUTO_MODE`: Automatically discovers and selects the most relevant datasets for the user's queries. -* `DATA_SOURCE`: Sets the target context as the data source. You must specify at least one data source ID. -** To set a single data source object metadata context, specify a `data_source_identifier`. -** For multi-data source context, specify the `data_source_identifiers`. -+ -[IMPORTANT] -==== -The `data_source` and `guid` attributes are deprecated in the 26.5.0.cl release version. Integrations using these parameters in ThoughtSpot versions 26.2.0.cl through 26.4.0.cl will continue to work until further notice. However, ThoughtSpot recommends using either `AUTO_MODE` or `DATA_SOURCE` with `data_source_identifier` or `data_source_identifiers` for the metadata context. -==== - -Other context options:: -The `answer_context` and `liveboard_context` are removed and no longer supported. Any existing integration or embedding application passing `answer_context` or `liveboard_context` in the request body must update their workflows to use the `AUTO_MODE` or `DATA_SOURCE` option. - -Enable save chat:: -The `enable_save_chat` parameter, when set to `true`, saves the conversation. - -API response:: -The API response now returns the `conversation_identifier`, which is used in all -subsequent send message or SSE streaming calls. - -=== Liveboard report API enhancements [beta betaBackground]^Beta^ -The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: - -* `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. -* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. - -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. - -== Version 26.4.0.cl, April 2026 - -=== Variable API endpoints -The following endpoints are introduced for bulk delete and update operations for variables: - -* `POST /api/rest/2.0/template/variables/{identifier}/update-values` + -Assigns multiple values to a variable and sets the scope for variable values in a single API request. -* `POST /api/rest/2.0/template/variables/delete` + -Deletes one or more variables in a single API request. - -These new API endpoints replace the following legacy API endpoints deprecated in 26.4.0.cl. - -* `POST /api/rest/2.0/template/variables/{identifier}/delete` -* `POST /api/rest/2.0/template/variables/update-values` - -Your existing implementation with the legacy API endpoints will continue to work until further notice. However, these endpoints will be removed from ThoughtSpot in a future release. Hence, we recommend updating your workflows to use the API endpoints at your earliest convenience. - -For more information, see xref:variables.adoc[Variable API documentation]. - -=== Metadata parameterization -You can now parameterize multiple fields in a metadata object in a single API request using the `/api/rest/2.0/metadata/parameterize-fields` API endpoint. -This endpoint replaces the legacy `/api/rest/2.0/metadata/parameterize` endpoint, which is deprecated in 26.4.0.cl. - -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization API documentation]. - -=== Webhook integration -This release introduces the following features and enhancements to the webhook integration workflows: - -Custom HTTP headers in webhook requests:: -Administrators can configure custom HTTP headers to send in webhook requests triggered by ThoughtSpot, in addition to the standard HTTP and authentication headers. You can specify these headers in the `additional_headers` attribute during webhook creation (`/api/rest/2.0/webhooks/create`) and update (`/api/rest/2.0/webhooks/{webhook_identifier}/update`) via REST APIs. - -Webhook connection validation:: -You can now validate a webhook connection by sending a test payload via an API request to the `/api/rest/2.0/system/communication-channels/validate` endpoint. The API returns a response indicating the connection and authentication status for a given webhook connection. - -Webhook monitoring:: -To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. - -For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. - -=== Collections API endpoints - -The following APIs are introduced for Collections: - -* `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + -Creates a new Collection. -* `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + -Searches for a Collection in ThoughtSpot -* `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + -Updates an existing Collection -* `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + -Deletes a Collection - -For more information, see xref:collections.adoc[Collections]. - -=== Email customization API enhancements - -The `template_properties` parameter now has the `hide_logo_url` elements for email template customization. Set it to `true` to entirely hide the logo component in the ThoughtSpot notification emails. - -=== Spotter API enhancements -Spotter AI APIs now support the following error responses: - -* 401 Unauthorized: authentication token is missing, expired, or invalid. -* 403 Forbidden: the authenticated user does not have `CAN_USE_SPOTTER` privilege or view access to the underlying metadata sources. - -=== Pivot table .xlsx exports -The following API endpoints now support pivot tables in `.xlsx` downloads with full visual and structural parity: - -* `POST /api/rest/2.0/report/answer` -* `POST /api/rest/2.0/schedules/create` - -To enable pivot formatting on your ThoughtSpot instance, contact ThoughtSpot Support. - -== Version 26.3.0.cl, March 2026 - -=== Webhook APIs - -The Webhook API allows configuring Amazon S3 buckets as a storage destination for webhook payload delivery. - -* `POST /api/rest/2.0/webhooks/create` + -Configures storage destination for webhook delivery. -* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + -Allows modifying storage configuration for a webhook. -* `POST /api/rest/2.0/webhooks/search` + -Retrieves storage configuration details. - -=== Object privilege APIs -Administrators and users with edit access to data models can now use `/api/rest/2.0/security/metadata/manage-object-privilege` to assign object-level permissions to users and groups and control access to Spotter data model instructions. - -To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. - -For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. - - -=== User API enhancements - -The user APIs now support setting browser language as the default locale for ThoughtSpot users. Administrators can set the `use_browser_language` parameter as the default locale for ThoughtSpot users during the following API operations: - -* When creating a new user via `POST /api/rest/2.0/users/create` + -* When importing users via `POST /api/rest/2.0/users/import` + -* When updating user preferences via `POST /api/rest/2.0/users/{user_identifier}/update` + - -When set to `true`, a user's current locale preference is overridden and the browser's language takes precedence. - -The status of the browser language setting for a given user can also be retrieved using the following API endpoints: - -* `POST /api/rest/2.0/users/search` + -* `POST /api/rest/2.0/users/activate` + -* `GET /api/rest/2.0/auth/session/user` + - -=== Custom token generation API -Note the following changes to request parameters for the `/api/rest/2.0/auth/token/custom` API endpoint: - -* The `filter_rules` parameter on the custom token authentication (`/api/rest/2.0/auth/token/custom`) page in the REST API Playground is no longer available for new configurations. Existing implementations that use `filter_rules` continue to work. However, we strongly recommend migrating to `variable_values` and ABAC via RLS for data security. - -* The `parameter_values` property is supported in the current release but will be deprecated in an upcoming version. Using `parameter_values` for row-level security will be phased out with this deprecation. Therefore, we recommend generating JWTs that pass data security attributes through formula variable attributes instead of `filter_rules` or `parameter_values` for ABAC. - -For more information, see xref:abac-migration-guide.adoc[ABAC JWT migration guide] and xref:abac_rls-variables.adoc[ABAC via RLS]. - -== 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 a 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 - -This release introduces the following Spotter APIs: - -* `POST /api/rest/2.0/ai/instructions/set` + -Allows configuring natural language (NL) instructions on a data model to define how Spotter interprets queries, handles data nuances, and improves responses. -* `POST /api/rest/2.0/ai/instructions/get` + -Gets NL instructions that are currently assigned to a model. -* `POST /api/rest/2.0/ai/data-source-suggestions` + -Retrieves a list of recommended data sources based on the specified query string. - -For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. - -=== Variable APIs - -You can now create formula variables using the `/api/rest/2.0/template/variables/create` API endpoint, and assign values and scope to these variables using the `/api/rest/2.0/template/variables/update-values` API endpoint. - -For more information, see xref:variables.adoc[Configure variables]. - -=== ABAC tokens with formula variable attributes -The `/api/rest/2.0/auth/token/custom` API endpoint allows creating a token request with formula variables for ABAC via RLS implementation. - -For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. - -== Version 10.14.0.cl, November 2025 - -=== New API endpoints - - - -System:: -This release introduces the following endpoints for configuring communication channel preferences. - -* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + -Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. -* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + -Gets details of the communication channel preferences configured on ThoughtSpot. -+ -For more information, see xref:webhooks-lb-schedule.adoc#_configure_a_webhook_communication_channel[Configure communication channel settings]. - -Webhook:: -The following APIs are introduced for webhook CRUD operations: -* `POST /api/rest/2.0/webhooks/create` -Creates a webhook. -* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` -Updates the properties of a webhook. -* `POST /api/rest/2.0/webhooks/search` -Gets a list of webhooks configured in ThoughtSpot or in a specific Org. -* `POST /api/rest/2.0/webhooks/delete` -Deletes the webhook. -+ -For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. - -Column security rules:: - -* `POST /api/rest/2.0/security/column/rules/update` + -Updates column security rules for a given Table. - -* `POST /api/rest/2.0/security/column/rules/fetch` + -Gets details of column security rules for the tables specified in the API request. - -//// - -Spotter:: -POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse -//// -=== Variable API enhancements - -The variable API enhancements are listed in the following sections. For additional details, see xref:variables.adoc[Define variables]. - -==== Variable creation API - -* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. -* The `sensitive` parameter is renamed as `is_sensitive`. -//* You can define the data type for variables using the `data_type`property. -//* You can now create formula variables. To create a formula variable, use define the variable type as `FORMULA_VARIABLE` variable type in your API request . - -==== Variables update APIs [tag redBackground]#BREAKING CHANGE# - -The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/update-values`. + -To update the properties of a specific variable, use the `/api/rest/2.0/template/variables/{identifier}/update` endpoint and to assign values to one or several variables in a single API call, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. - -==== Variables search API - -* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. -* Filtering API response by `EDITABLE_METADATA_AND_VALUES` is no longer supported. - - -=== User API enhancements -The following APIs now support the `variable_values` parameter. The `variable_values` property can be used for user-specific customization. - -* `POST /api/rest/2.0/users/create` -* `POST /api/rest/2.0/users/search` -* `POST /api/rest/2.0/users/activate` - -=== DBT API enhancements -The `/api/rest/2.0/dbt/generate-tml` endpoint supports the `model_tables` attribute to list models and their tables. - -//// - -=== Authentication API -Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. - -//// - -== Version 10.13.0.cl, October 2025 - -=== New API endpoints - -Spotter:: - -* `POST /api/rest/2.0/ai/agent/conversation/create` + -Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + - - -* `POST /api/rest/2.0/ai/relevant-questions/` + -Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. - -* `POST /api/rest/2.0/ai/agent/converse/sse` + -Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + - -//* `POST /api/rest/2.0/ai/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. + - -For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. - -Email customization:: -`POST /api/rest/2.0/customization/email/update` + -Updates an existing email customization. For more information, see xref:customize-email-apis.adoc[Customize email template]. - -=== API enhancements -The following APIs were modified to include new parameters: - -TML export:: -The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. - -Email customization:: -The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. - -For more information, see xref:customize-email-apis.adoc[Customize email template]. - -=== Deprecated endpoints - -Spotter:: -The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. - -Email customization:: -The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete`. - - -//// -=== Deprecated endpoints -The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. - -* `POST /api/rest/2.0/ai/conversation/create` -* `POST /api/rest/2.0/ai/analytical-questions` -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` -//// - -== Version 10.12.0.cl, September 2025 - -=== New API endpoints - -The following API endpoints are now available: - -Custom calendar:: -* `POST /api/rest/2.0/calendars/create` + -Creates a custom calendar. -* `POST /api/rest/2.0/calendars/generate-csv` + -Exports a custom calendar in the CSV format. -* `POST /api/rest/2.0/calendars/search` + -Gets custom calendars for the connection ID specified in the API request. -* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + -Deletes a custom calendar. -* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + -Updates a custom calendar. - -Connection configuration:: -* `POST /api/rest/2.0/connection-configurations/create` + -Creates an additional configuration to an existing connection to a data warehouse. -* `POST /api/rest/2.0/connection-configurations/search` + -Gets the required connection configuration objects. -* `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + -Updates an existing connection configuration object. -* `POST /api/rest/2.0/connection-configurations/delete` + -Deletes the connection configuration object. - -=== Enhancements to APIs - -Export API endpoint:: - -* Answer TML: + -The `POST /api/rest/2.0/metadata/tml/export` API endpoint now allows fetching TML for Answer objects that do not have an ID or name assigned. The `session_identifier` and `generation_number` parameters allow you to define the session ID and the Answer generation number in the API request. These optional attributes can be used for unsaved Answers generated from Spotter queries. - -* Table TML: + -The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column security rules for Table TML objects. This attribute will export column security rules only if the object specified in the API request has column security applied and when `export_associated` is set to `true`. - -== Version 10.11.0.cl, July 2025 - -=== Search metadata API enhancements -The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: - -* The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. -* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. -* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. - - -=== System API -The API response generated from the `GET /api/rest/2.0/system/config-overrides` requests now returns the overrides in the `config_override_info` object. - -=== TML API -The API response for the `POST /api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/async/status` now includes the `author_display_name` property. This property shows the display name of user that initiated the asynchronous TML import request. - -=== REST API Java SDK - -The REST API Java SDK library artifacts are now available in the `com.thoughtspot` Maven namespace. If you are using Maven Central to import the REST API SDK artifacts, update the group ID in your `pom.xml` file to `com.thoughtspot` and the artifact ID to `rest-api-sdk`. - -For more information, see xref:rest-api-java-sdk.adoc#_import_the_sdk_to_your_application_environment[REST API Java SDK]. - -== Version 10.10.0.cl, July 2025 - -=== Email template customization APIs -This release introduces the following new endpoints for email template customization: - -* `POST /api/rest/2.0/customization/email` + -Allows you to personalize the ThoughtSpot notification emails content. -* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + -Removes the customizations done for the ThoughtSpot notification emails. -* `POST /api/rest/2.0/customization/email/search` + -Allows searching the email customization configuration if configured for ThoughtSpot. -* `POST /api/rest/2.0/customization/email/validate` + -Validates the email customization configuration if configured for ThoughtSpot. - -=== Group API - -The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: - -* `include_users` + -When set to `true`, it includes user details in the group search API response. -* `include_sub_groups` + -When set to `true`, it includes sub-groups in the group search response. - -=== Schedule API -You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: - -* `POST /api/rest/2.0/schedules/create` -To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. -* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` -To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. - -== Version 10.9.0.cl, June 2025 - -=== Metadata parameterization and content publishing across Orgs - -This release introduces the following new endpoints for metadata parameterization [beta betaBackground]^Beta^ and content publishing [beta betaBackground]^Beta^ across Orgs. To enable the content publishing feature and the related API operations on your instance, contact ThoughtSpot Support. - -* `POST /api/rest/2.0/metadata/parameterize` [beta betaBackground]^Beta^ + -Allows you to parameterize fields in metadata objects. -* `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + -Allows removing parameterization from fields in metadata objects -* `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + -Publish metadata objects to one or several Orgs on an instance. -* `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + -Removes published metadata objects from the Orgs specified in the API request. -* `POST /api/rest/2.0/template/variables/create` [beta betaBackground]^Beta^ + -Allows creating a template variable which can be used to parameterize fields in a metadata object. -* `POST /api/rest/2.0/template/variables/search` [beta betaBackground]^Beta^ + -Allows searching template variables -* `POST /api/rest/2.0/template/variables/{identifier}/update` [beta betaBackground]^Beta^ + -Allows updating properties of a template variable. -* `POST /api/rest/2.0/template/variables/update` [beta betaBackground]^Beta^ + -Allows you to add, remove, or replace properties of one or several template variables. -* `POST /api/rest/2.0/template/variables/{identifier}/delete` [beta betaBackground]^Beta^ + -Deletes a template variable. - -If your metadata objects are parameterized, you can use the `show_resolved_parameters` to filter the API response from `/api/rest/2.0/connection/search` and `/api/rest/2.0/metadata/search` endpoints to get only the objects with resolved parameterized values. - -=== Liveboard Report API -The Liveboard Report API now allows you to define the following properties: - -* `tab_identifiers` + -Optional parameter to specify the name or GUID of a Liveboard tab to export only the visualizations in that tab. -* `personalised_view_identifier` + -Optional parameter to specify the GUID of the Liveboard personalized view that you want to download. - -In addition to these parameters, you can also define the following properties for PNG downloads: - -* `image_resolution` -* `image_scale` -* `include_header` - -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. - -=== REST API Java SDK - -The REST API Java SDK enables developers to interact programmatically with ThoughtSpot REST APIs from Java applications. It provides a client library with Java methods and classes that map to API endpoints, handle authentication, send API requests, and allow creating and modifying ThoughtSpot resources and objects. - -For information about how to install and use the SDK, see xref:rest-api-java-sdk.adoc[Java SDK for REST APIs]. - - -== Version 10.8.0.cl, April 2025 - -=== New API endpoints - -This version introduces the following endpoints: -//// -* `POST /api/rest/2.0/ai/analytical-questions` + -Allows using an existing ThoughtSpot Answer or Liveboard, and include content to improve query response. -//// - -* `POST /api/rest/2.0/metadata/update-obj-id` + -Update object IDs for given metadata objects. + - -[NOTE] -==== -An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. -Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. -==== - -=== Metadata API - -* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: - -** `include_discoverable_objects` + -Allows including Answers and Liveboards that are marked as discoverable by the object owner. -** `metadata_obj_id` + -Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. - -=== TML APIs - -* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. - -* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. - -=== Report APIs -The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. - -For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. - -== Version 10.6.0.cl, March 2025 - -=== New metadata API endpoints - -* `POST /api/rest/2.0/metadata/headers/update` + -Updates metadata header for a given list of objects. -* `POST /api/rest/2.0/metadata/worksheets/convert` + -Converts a Worksheet object to a Model. - -=== Report APIs -[tag redBackground]#BREAKING CHANGE# - -Downloading Liveboard reports in the CSV and XLSX file format via `POST /api/rest/2.0/report/liveboard` API endpoint is not supported. The CSV and XLSX `file_format` options have been removed because they were not functioning in the expected manner. - -==== Parameters for regional settings - -The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow users to define the following `regional_settings` attributes: - -* `currency_format` -* `user_locale` -* `number_format_locale` -* `date_format_locale` - -//// -=== Custom authentication token API - -The `/api/rest/2.0/auth/token/custom` API endpoint now allows you to define the `reset_option` to specify if the attributes assigned to the token should persist or be reset. -//// - -=== Custom object ID in TML and Metadata APIs - -The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: - -* `POST /api/rest/2.0/metadata/search` -* `POST /api/rest/2.0/metadata/headers/update` -* `POST /api/rest/2.0/metadata/tml/export` + - -=== TML import API - -The `/api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/import` endpoints allow skipping diff check when processing TMLs for imports. The `skip_diff_check` attribute is disabled by default and can be enabled to avoid importing objects that do not have any changes. - -=== API response changes - -The 200 and 201 response body from `POST /api/rest/2.0/ai/answer/create` and `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API calls now includes the `display_tokens` property. - - -== Version 10.5.0.cl, December 2024 - -=== Custom access token API -The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: - -* `auto_create` + -Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. -* `REPLACE` enum for `persist_option` + -Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. - -=== TML import APIs - -TML async import:: - -The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: -+ -* `import_policy` + -Allows you to specify if all objects should be imported during the TML import operation. Valid values are: - -** `PARTIAL_OBJECT` (default) -** `PARTIAL` -** `VALIDATE_ONLY` -** `ALL_OR_NONE` - -* `enable_large_metadata_validation` + -Indicates if the TMLs with large and complex metadata should be validated before the import. -+ -For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. - -//// -* `skip_diff_check` + -Allows skipping checks that find differences in TML content before processing TML objects for import. -//// - -TML import API:: - -The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. - -TML export API:: - -The `/api/rest/2.0/metadata/tml/export` endpoint now allows you to include additional attributes when exporting TML for an object from ThoughtSpot. The `export_options` allows you to include the following optional attributes: - -* `include_obj_id_ref` + -Specifies whether to export `user_defined_id` of the referenced object. This setting is valid only if the `UserDefinedId` property in TML is enabled. -* `include_guid` + -Specifies whether to export the GUID of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. -* `include_obj_id` + -Specifies whether to export the `user_defined_id` of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. - - -Share metadata:: - -The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. - -Role API:: - -The `/api/rest/2.0/roles/create` API endpoint now allows setting `read_only` attribute to specify if the role is read only. A read-only role cannot be updated or deleted. - -== Version 10.4.0.cl, November 2024 - -=== New API endpoints - -Spotter AI APIs [beta betaBackground]^Beta^ :: - -* `POST /api/rest/2.0/ai/conversation/create` + -Creates a conversation session. -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + -Generates responses for user queries and follow-up questions. -* `POST /api/rest/2.0/ai/answer/create` + -Generates an Answer from a Natural Language Search query. - -Authentication:: -The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. - -+ -ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. - -Connections:: -The following new API endpoints are available for updating and deleting a connection object: - -* `POST /api/rest/2.0/connections/{connection_identifier}/update` -* `POST /api/rest/2.0/connections/{connection_identifier}/delete` - -+ -ThoughtSpot recommends using these APIs instead of `POST /api/rest/2.0/connection/update` and `POST /api/rest/2.0/connection/delete`. - -TML:: -The following API endpoints are available for asynchronous TML import: - -* `POST /api/rest/2.0/metadata/tml/async/import` + -Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects. -* `POST /api/rest/2.0/metadata/tml/async/status` + -Fetches task status for the async TML import operations. - -For more information, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. - -=== API enhancements - -User session:: - -* The 200 API response for the `/api/rest/2.0/auth/session/user` and `/api/rest/2.0/users/search` is modified to show `access_control_properties`. - -* You can now manage account activation status for IAMv2 users using the following API endpoints: - -** `POST /api/rest/2.0/users/create` + -** `POST /api/rest/2.0/users/{user_identifier}/update` - -//// -TML import API:: -You can specify the following attributes in TML import requests to `/api/rest/2.0/metadata/tml/import`: - -* `skip_cdw_validation_for_tables` + -Indicates if the Cloud Data Warehouse (CDW) validation for table imports should be skipped. -//// - -Report API:: - -The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: - -* `session_identifier` + -Session ID returned in API response by the `/api/rest/2.0/ai/answer/create` or `/api/rest/2.0/ai/conversation/create` endpoint. -* `generation_number` + -Number assigned to the Answer session with Spotter. -+ -If you are downloading an Answer generated by Spotter, you must specify the session ID. The `metadata_identifier` property is not required. - -=== Deprecated features - -Connection APIs:: - -The following connection API endpoints are deprecated: - -* `POST /api/rest/2.0/connection/delete` -* `POST /api/rest/2.0/connection/update` - -+ -Use `POST /api/rest/2.0/connections/{connection_identifier}/update` and `POST /api/rest/2.0/connections/{connection_identifier}/delete` APIs to update and delete a connection object respectively. - -Authentication:: - -The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated. -+ -ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` API endpoint with `filter_rules` and `parameter_values` to configure user properties for ABAC via tokens. - -== Version 10.3.0.cl, October 2024 - -=== New API endpoint - -You can now create a copy of a Liveboard or Answer object using `/api/rest/2.0/metadata/copyobject` API endpoint. - -== Version 10.1.0.cl, August 2024 - -=== New API endpoints - -* `POST /api/rest/2.0/metadata/tml/export/batch` + -Exports a batch of TML for user, user group, or Role objects. - -=== Security APIs -The `/api/rest/2.0/security/metadata/fetch-permissions` API endpoint supports the following parameters: - -* `record_offset` + -Specifies the starting record number from which the records for each metadata type will be included in the API response. -* `record_size` + -Specifies the number of records that should be included for each metadata type in the API response. -* `permission_type` + -Specifies the type of permission. Valid values are: -** `EFFECTIVE` - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong. -** `DEFINED` - If a user or user group received access to metadata objects via object sharing by another user. - -== Version 10.0.0.cl, July 2024 - -=== Roles - -You can now assign the `CAN_MANAGE_VERSION_CONTROL` role using any of the following API endpoints: - -* `POST /api/rest/2.0/roles/create` -* `POST /api/rest/2.0/roles/{role_identifier}/update` - -The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration with ThoughtSpot. - -== Version 9.12.0.cl, May 2024 - -==== New features - -Authentication API:: - -* `/api/rest/2.0/auth/token/validate` + -Validates the authentication token of the logged-in user. - -TML API:: -The export TML API requests now support the following parameters: -+ -* `export_schema_version` + -Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set `export_schema_version` to `v2`. + -* `export_dependent` + -Allows exporting dependent Tables while exporting a Connection. -* `export_connection_as_dependent` + -Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. - -==== Deprecated features - -Token authentication APIs:: - -The `jwt_user_options` object property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated. Use the `user_parameters` property to define security entitlements to a user session. For more information, see xref:abac-user-parameters.adoc[ABAC via token][beta betaBackground]^Beta^. - -== Version 9.10.5.cl, April 2024 - -=== New features - -Authentication:: - -The `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints support generating JWT token for Attribute-Based Access Control. The `user_parameters` object allows you to define security entitlements for a given user. - -For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. - -Roles:: - -The `/api/rest/2.0/roles/create` and `/api/rest/2.0/roles/{role_identifier}/update` API endpoints support assigning the following privileges to a Role for granular data access control and management: - -* `CAN_MANAGE_CUSTOM_CALENDAR` -* `CAN_CREATE_OR_EDIT_CONNECTIONS` -* `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` - -DBT:: - -You can now use `file_content` to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the `/api/rest/2.0/dbt/dbt-connection`, `/api/rest/2.0/dbt/generate-tml`, `/api/rest/2.0/dbt/generate-sync-tml`, and `/api/rest/2.0/dbt/update-dbt-connection` endpoints. This field is required if the `import_type` parameter is set to `'ZIP_FILE'`. - -Connections:: - -* `/api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + -Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot. -* `/api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + -Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot. - -Logs:: -The `/api/rest/2.0/logs/fetch` API endpoint allows fetching all logs in a single API request. To get all logs, set `get_all_logs` to `true`. - -Share metadata:: - -The `/api/rest/2.0/security/metadata/share` API supports the following new properties: - -* `notify_on_share` + -Sends a share notification to the email addresses specified in the API request. -* `has_lenient_discoverability` + -Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only. - -Users:: -The `trigger_activation_email` property allows you to specify if an activation email must be sent to the user's email address in the user creation request to the `/api/rest/2.0/users/create` endpoint. - -=== Deprecated features - -Version Control APIs:: - -The following parameters in `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` are deprecated from 9.10.5.cl onward: - -* `default_branch_name` + -Replaced by `commit_branch_name` -* `guid_mapping_branch_name` + -Replaced by `configuration_branch_name` - -For more information, see xref:version_control.adoc[Git integration and version control]. - -== Version 9.10.0.cl, March 2024 - -=== New API endpoints - -DBT:: - -* `POST /api/rest/2.0/dbt/dbt-connection` + -Creates a DBT connection. -* `POST /api/rest/2.0/dbt/generate-tml` + -Generates Worksheets and Tables for a given DBT connection. -* `POST /api/rest/2.0/dbt/generate-sync-tml` + -Synchronizes the existing TML of data models and Worksheets and imports them to ThoughtSpot. -* `POST /api/rest/2.0/dbt/search` + -Gets a list of DBT connection objects for a given user or Org. -* `POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + -Updates a DBT connection. - -System:: - -`GET api/rest/2.0/system/banner` + -Gets cluster maintenance status and banner text. - -+ -For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[Cluster maintenance and upgrade]. - -== Version 9.8.0.cl, January 2024 - -The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. - -== Version 9.7.0, November 2023 - -=== Version Control APIs - -This release introduces the following enhancements to the Version Control API endpoints: - -==== Git connection creation and update APIs - -The `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints include the following enhancements: - -New parameters:: - -* `commit_branch_name` + -Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using `commit_branch_name` instead of `default_branch_name` in the API calls to prevent users from committing changes to the default deployment branch. -* `configuration_branch_name` + -Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the `configuration_branch_name` property is defined, the `guid_mapping_branch_name` parameter is not required. - -Modified parameters:: -The `enable_guid_mapping` parameter is enabled by default. - -Separate branches for Orgs:: -If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git `repository_url`, the `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints do not support configuring the same branch name for these Orgs. - -Deprecation notice:: - -The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. - -For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. - -==== Commit API - -The `POST /api/rest/2.0/vcs/git/branches/commit` API endpoint allows the following new attribute in the request body: - -* `delete_aware` -+ -When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation. - -For more information, see xref:version_control.adoc#_commit_files_and_changes[Commit files]. - -==== Deploy API - -Note the following changes: - -* The `branch_name` attribute is now mandatory in the `POST /api/rest/2.0/vcs/git/commits/deploy` API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org. - -* After a successful deployment, a tracking file is generated with the `commit_id` and saved in the Git branch that is used for storing configuration files. The `commit_id` recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls. - -For more information, see xref:version_control.adoc#_deploy_commits[Deploy commits]. - -=== User API - -The following new API endpoints are introduced for user account management: - -* `POST /api/rest/2.0/users/activate` + -Activates an inactive user account. - -* `POST /api/rest/2.0/users/deactivate` + -Deactivates a user account. - -=== Support for sorting of columns at runtime -The following data API endpoints now support runtime sorting of columns: - -* `POST /api/rest/2.0/searchdata` + -* `POST /api/rest/2.0/metadata/liveboard/data` + -* `POST /api/rest/2.0/metadata/answer/data` + - -For more information, see xref:runtime-sort.adoc[Runtime sorting of columns]. - -== Version 9.6.0.cl, October 2023 - -=== New API endpoints - -* `POST /api/rest/2.0/customization/custom-actions/search` + -Gets custom action objects -* `POST /api/rest/2.0/customization/custom-actions` + -Creates a custom action -* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + -Updates the properties of a custom action object. -* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + -Deletes a custom action - -=== SDK for TypeScript - -ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk?activeTab=readme[NPM site, window=_blank]. - -== Version 9.5.0.cl, September 2023 - -=== New API endpoints for Role-Based Access Control [beta betaBackground]^Beta^ - -* `POST /api/rest/2.0/roles/search` + -Gets details of role objects available in the ThoughtSpot system. -* `POST /api/rest/2.0/roles/create` + -Creates a role and assigns privileges -* `POST /api/rest/2.0/roles/{role_identifier}/update` + -Updates the properties of a given role -* `POST /api/rest/2.0/roles/{role_identifier}/delete` + -Removes a role object from the ThoughtSpot system - -For more information, see xref:roles.adoc[Role-based access control]. - -[NOTE] -==== -The roles APIs work only if the Role-Based Access Control (RBAC) [beta betaBackground]^Beta^ feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support. -==== - -=== Enhancements and API modifications - -Support for runtime parameter overrides:: -The following data and report API endpoints support applying runtime parameter overrides: -* `POST /api/rest/2.0/searchdata` + -* `POST /api/rest/2.0/metadata/liveboard/data` + -* `POST /api/rest/2.0/metadata/answer/data` + -* `POST /api/rest/2.0/report/liveboard` + -* `POST /api/rest/2.0/report/answer` - -Git integration support for Orgs:: - -The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for `dev`, `staging`, and `prod` and integrate these environments with a GitHub repo. - -+ -For more information, see xref:version_control.adoc[Git integration and version control]. - -=== Response code change [tag redBackground]#BREAKING CHANGE# - -The following endpoints now return the 204 response code instead of 200. The 204 code does not return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues. - -* `POST /api/rest/2.0/connection/delete` -* `POST /api/rest/2.0/connection/update` -* `POST /api/rest/2.0/users/{user_identifier}/update` -* `POST /api/rest/2.0/users/{user_identifier}/delete` -* `POST /api/rest/2.0/users/change-password` -* `POST /api/rest/2.0/users/reset-password` -* `POST /api/rest/2.0/users/force-logout` -* `POST /api/rest/2.0/groups/{group_identifier}/update` -* `POST /api/rest/2.0/groups/{group_identifier}/delete` -* `POST /api/rest/2.0/metadata/delete` -* `POST /api/rest/2.0/orgs/{org_identifier}/update` -* `POST /api/rest/2.0/orgs/{org_identifier}/delete` -* `POST /api/rest/2.0/schedules/{schedule_identifier}/delete` -* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` -* `POST /api/rest/2.0/security/metadata/assign` -* `POST /api/rest/2.0/security/metadata/share` -* `POST /api/rest/2.0/system/config-update` -* `POST /api/rest/2.0/tags/{tag_identifier}/update` -* `POST /api/rest/2.0/tags/{tag_identifier}/delete` -* `POST /api/rest/2.0/tags/assign` -* `POST /api/rest/2.0/tags/unassign` -* `POST /api/rest/2.0/vcs/git/config/delete` -* `POST /api/rest/2.0/auth/session/login` -* `POST /api/rest/2.0/auth/session/logout` -* `POST /api/rest/2.0/auth/token/revoke` - - -== Version 9.4.0.cl, August 2023 - -=== API endpoints to schedule and manage Liveboard jobs - -* `*POST* /api/rest/2.0/schedules/create` + -Creates a scheduled job for a Liveboard -* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/update` + -Updates a scheduled job -* `*POST* /api/rest/2.0/schedules/search` + -Gets a list of Liveboard jobs configured on a ThoughtSpot instance -* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/delete` + -Deletes a scheduled job. - -For more information, see link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fschedules%2Fsearch-schedule[REST API v2.0 Reference]. - -=== API to fetch authentication token - -The `GET /api/rest/2.0/auth/session/token` API endpoint fetches the current authentication token used by the currently logged-in user. - -=== Version Control API enhancements - -* The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance: - -** `*POST* /api/rest/2.0/vcs/git/config/create` -** `*POST* /api/rest/2.0/vcs/git/config/update` - -=== User and group API enhancements - -* The `**POST** /api/rest/2.0/users/{user_identifier}/update` and `**POST** /api/rest/2.0/groups/{group_identifier}/update` support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the `operation` type as `REMOVE` in the API request. -* The `**POST** /api/rest/2.0/users/{user_identifier}/update` allows you to define locale settings, preferences, and other properties for a user object. - -== Version 9.3.0.cl, June 2023 - -The following Version Control [beta betaBackground]^Beta^ API endpoints are now available for the lifecycle management of content on your deployment environments: - -* `*POST* /api/rest/2.0/vcs/git/config/search` -* `*POST* /api/rest/2.0/vcs/git/commits/search` -* `*POST* /api/rest/2.0/vcs/git/config/create` -* `*POST* /api/rest/2.0/vcs/git/config/update` -* `*POST* /api/rest/2.0/vcs/git/config/delete` -* `*POST* /api/rest/2.0/vcs/git/branches/commit` -* `*POST* /api/rest/2.0/vcs/git/commits/{commit_id}/revert` -* `*POST* /api/rest/2.0/vcs/git/branches/validate` -* `*POST* /api/rest/2.0/vcs/git/commits/deploy` - -For more information, see xref:version_control.adoc[Version control and Git integration]. - -== Version 9.2.0.cl, May 2023 - -New endpoints:: - -* System -+ -** `POST /api/rest/2.0/system/config-update` + -Updates system configuration -+ -** `GET /api/rest/2.0/system/config-overrides` + -Gets system configuration overrides - -* Connections -+ -** POST /api/rest/2.0/connection/create + -Creates a data connection - -** `POST /api/rest/2.0/connection/search` + -Gets a list of data connections - -** `POST /api/rest/2.0/connection/update` + -Updates a data connection - -** `POST /api/rest/2.0/connection/delete` + -Deletes a data connection - -Enhancements:: - -* Support for runtime filters and runtime sorting of columns + -The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_apply_runtime_filters_in_rest_api_v2_requests[runtime filters] and xref:runtime-sort.adoc[sorting column data]: -+ -** `POST /api/rest/2.0/report/liveboard` + -** `POST /api/rest/2.0/report/answer` - -* Search users by their favorites -+ -The `/api/rest/2.0/users/search` API endpoint allows searching users by their favorite objects and home Liveboard setting. - -* Ability to log in to a specific Org -+ -The `/api/rest/2.0/auth/session/login` API endpoint now allows ThoughtSpot users to log in to a specific Org context. - -== Version 9.0.0.cl, February 2023 - -The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: +Exports from this endpoint inherently reflect any row-level security (RLS) applied to the underlying data. -* xref:rest-api-v2.adoc[REST API v2.0] -* xref:rest-api-v2-getstarted.adoc[Get started with REST API v2.0] -* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] -* xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison] +Transient content export:: +// SOURCE: SCAL-306548 +You can now export a transient Answer using the Answer report API. To export a transient Answer, specify the `transient_content` parameter in your API request. From 4bca3d8b3dc8be6fdb95a135bb75cebd16b6d9c6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:37:27 +0530 Subject: [PATCH 08/63] =?UTF-8?q?docs(tml):=20add=2026.8.0.cl=20=E2=80=94?= =?UTF-8?q?=20Personalized=20Views=20portability=20(owned=5Fby,=20obj=5Fid?= =?UTF-8?q?)=20and=20Collections=20obj=5Fid=20support=20[SCAL-307283,=20SC?= =?UTF-8?q?AL-317357]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/tml.adoc | 474 ++++++++---------------------------- 1 file changed, 107 insertions(+), 367 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 9ffba0d70..84bf60c88 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -8,6 +8,81 @@ ThoughtSpot Modeling Language (TML) is a scriptable format developed by ThoughtSpot for exporting, modifying, and migrating metadata objects such as Models, Views, Tables, Liveboards, and Answers. TML files allow you to manage and version control these objects outside the ThoughtSpot UI, supporting workflows like bulk changes, migration between environments, and programmatic edits via REST API. Users can use link:https://docs.thoughtspot.com/cloud/latest/tml[TML] to model data and build analytics content in the test environment in a flat-file format, and then import and deploy it in their environments. +// SOURCE: SCAL-307283, SCAL-317357 +// TODO: [WRITER] Confirm exact TML field names `owned_by` and `obj_id` in the Personalized View TML schema with the TML/deployment team before publishing. +// TODO: [WRITER] Confirm the smart merge behavior for `obj_id`: does a match update the existing view, skip import, or prompt the user? +// TODO: [WRITER] Confirm whether `obj_id` is present in TML export output for Collections by default in 26.8.0.cl, or must it be explicitly requested. +// TODO: [WRITER] Confirm the correct `metadata_type` value for Collections in the identity update API (`POST /api/rest/2.0/metadata/identity/update`). Verify with the platform team. +// TODO: [WRITER] Add a cross-reference to the product docs TML page for Personalized Views once the product docs page is updated. + +[#personalized-views-portability] +== Personalized Views portability [.version-badge.new]#New in 26.8.0.cl# + +// SOURCE: SCAL-307283 +Starting from ThoughtSpot Cloud 26.8.0.cl, Personalized Views support improved portability across ThoughtSpot environments. Two new TML fields and updated import merge logic make it easier to migrate Personalized Views between development and production environments without creating duplicates. + +=== New TML fields for Personalized Views + +`owned_by`::: +// TODO: [WRITER] Confirm field name and accepted value types (username string vs. user GUID). +A new `owned_by` field is available in the Personalized View TML. Specify a username or user GUID in this field to assign ownership during import. If `owned_by` is omitted, the importing user becomes the owner by default. + +`obj_id`::: +// TODO: [WRITER] Confirm field name. Confirm whether obj_id is auto-generated on export or must be manually assigned before import. +A new `obj_id` field provides stable cross-environment object identity for Personalized Views. Use the same `obj_id` value across environments to ensure consistent identity during migrations. + +=== Smart merge on import + +When importing a Personalized View TML that contains an `obj_id`, ThoughtSpot checks the target environment for an existing Personalized View with a matching `obj_id`. If a match is found, the import updates the existing view rather than creating a duplicate. If no match is found, a new Personalized View is created. + +// TODO: [WRITER] Confirm: does the merge-on-match behavior apply only when `create_new` is set to `false` in the import request, or does it apply regardless of `create_new`? + +=== Example — Personalized View TML with portability fields + +[source,yaml] +---- +# TODO: [WRITER] Replace with a confirmed TML snippet from the product or TML team. +# The field names and structure below are inferred from the Jira description (SCAL-307283). +# Verify before publishing. +personalized_view: + name: Q4 Revenue View + obj_id: pv-abc123-def456 # Stable cross-environment identifier + owned_by: analyst@example.com # Owner assigned on import (username or GUID) + liveboard_id: lb-xyz789 # GUID of the parent Liveboard + filters: + - column: Region + values: [North America] +---- + +[#collections-obj-id] +== Collections `obj_id` in TML [.version-badge.new]#New in 26.8.0.cl# + +// SOURCE: SCAL-317357 +Starting from 26.8.0.cl, the `obj_id` attribute is supported for the *Collections* object type in TML import and export. This enables stable cross-environment identification for Collections, consistent with support already available for Models, Liveboards, Answers, and other object types. + +=== Assign or update a Collections `obj_id` + +To assign or update the `obj_id` for an existing Collections object, use the Metadata Identity Update API: + +// TODO: [WRITER] Confirm endpoint path and `metadata_type` value for Collections with the platform team. +[source,bash] +---- +curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/identity/update' \ + -H 'Authorization: Bearer {token}' \ + -H 'Content-Type: application/json' \ + -d '{ + "metadata": [ + { + "identifier": "", + "metadata_type": "COLLECTION", + "obj_id": "my-stable-collection-id" + } + ] + }' +---- + +After the `obj_id` is assigned, TML exports for this Collection include the `obj_id` field, enabling stable identity across environments. + == Structure of a TML file To work with TML files for Models, views, SQL views, tables, Answers, Liveboards, and Monitor alerts in ThoughtSpot, you can download these objects as a flat file in `.TML` format, modify, and subsequently upload the TMLs either to the same or a different cluster. @@ -50,7 +125,7 @@ You can import single or multiple objects using the `tml/import` API. If you are By default, the `fqn` parameter is not present in the TML file. However, you can export TML with FQNs and use it during the import. -You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven’t been changed since the last import or TML update, and eliminates importing redundant objects. +You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven't been changed since the last import or TML update, and eliminates importing redundant objects. To import TML representation of the metadata objects into ThoughtSpot, use one of the following API endpoints: @@ -97,392 +172,57 @@ You can import TML objects asynchronously by scheduling TML import tasks via `PO |Form parameter|Description| Default |`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ |`create_new` + -__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. | `false` -|`all_orgs_context` + -__Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. - -__Requires Org administration privileges to access TML objects across all Orgs.__| `false` - -|`import_policy` a|__String__. Available from 10.5.0.cl. Policy to follow during import. The allowed values are: - -* `PARTIAL` + -Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. -* `ALL_OR_NONE` + -Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. -* `VALIDATE_ONLY` + -Validates the objects but does not import them. -* `PARTIAL_OBJECT` + -Imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. -| `PARTIAL_OBJECT` - -|`skip_diff_check` + -__Optional__ -|__Boolean__. When set to `true`, skips the diff check before processing TML objects for import. By default, ThoughtSpot compares each TML object against its last imported version and skips objects that have not changed, which reduces unnecessary reimports. Set to `true` to bypass this check and reimport all objects regardless of whether they have changed. |`false` -|`enable_large_metadata_validation` + -__Optional__ - |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). -|`false` -|==== -//// - - +__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects.| `false` +|`import_policy` + +__Optional__ |__String__. Policy to import TML objects. + +Valid values are `PARTIAL`, `ALL_OR_NONE`, `VALIDATE_ONLY`, and `PARTIAL_OBJECT`. |`PARTIAL` +|`all_orgs_override` + +__Optional__ |__Boolean__. When set to `true`, the TML objects are imported in all Orgs.| `false` |`skip_cdw_validation_for_tables` + -__Optional__ |__Boolean__. Skips Cloud Data Warehouse validation for table TML imports. | `false` -//// -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/import' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_tmls": [ - "{\\\"guid\\\": \\\"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\\\",\\\"liveboard\\\": {\\\"name\\\": \\\"Total Sales\\\",\\\"visualizations\\\": [{\\\"id\\\": \\\"Viz_1\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total quantity purchased, Total sales by region\\\",\\\"description\\\": \\\"test\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[region] [quantity purchased] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total quantity purchased\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"region\\\",\\\"Total quantity purchased\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"region\\\"],\\\"y\\\": [\\\"Total quantity purchased\\\",\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"f6701821-5630-49cd-b26f-f98bebb4e98e\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total quantity purchased\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"1e086aef-236d-4cf0-8909-9e04e04a1ac4\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": true}},{\\\\\\\"id\\\\\\\": \\\\\\\"7be648d3-c791-43e4-bb13-63fea808f326\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"region\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total quantity purchased\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"b8b38851-5980-40a1-bd88-608b7a9c6e86\\\"},{\\\"id\\\": \\\"Viz_2\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales in a year\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [store] [date].monthly [date].'\''this year'\''\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Month(date)\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"store\\\",\\\"Month(date)\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"LINE\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"Month(date)\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"store\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"feb33c4a-614b-4623-9d12-1c4cf2250801\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"e89293cb-d10a-40d5-b787-81be33cc8b81\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Month(date)\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"6a4acb32-9036-4d4c-a830-f2b06966a322\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"39e5242e-43d0-4ef7-8673-73b12433e0c5\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (85226)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (86001)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (91006)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (94702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80301)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#8C62F5\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80920)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FF8142\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06110)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#ABC7F9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06854)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B5ECF2\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"delaware (19702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FDE9AF\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30022)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#9BE5CB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30329)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#D1C0FB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"idaho (83704)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFCCB3\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60062)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2359B6\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60642)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#369FAA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"indiana (46250)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#BF982A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"iowa (50266)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#049160\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"maryland (21045)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#6A4ABA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (01701)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#C26232\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (02215)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (48103)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#82DFE9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (49512)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCD977\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55369)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#56D3A8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55420)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B094F8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"missouri (63144)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFA97E\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59106)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#163772\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59718)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#22636B\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89052)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#785F1A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89145)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#025B3C\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new hampshire (03860)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#422E75\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new jersey (07936)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#7A3D1F\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"7efc7b0e-e680-44a4-ba9c-3bd5d7272367\\\"},{\\\"id\\\": \\\"Viz_3\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by item type and region\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [item type] [region]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"item type\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"item type\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"item type\\\",\\\"region\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"STACKED_COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"item type\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"item type\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"region\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"a330db6d-3714-4b5f-aed7-cca5ab679502\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"96ac1ce3-7efd-455e-a569-2cd0792b5f95\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"item type\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"92153012-664c-458e-9a74-6138c5030838\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"east\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"midwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"south\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"southwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"west\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"9de47a0e-6f20-40ba-9a52-3374ee530f09\\\"},{\\\"id\\\": \\\"Viz_4\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by state\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[state] [store] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"state\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"state\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"state\\\",\\\"store\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"GEO_AREA\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"state\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"state\\\"],\\\"y\\\": [\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"e4943da4-f159-470c-836b-7c6c55d59c2f\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"b99d582a-b215-4381-89ad-280c451979e3\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"state\\\\\\\"]}}],\\\\\\\"systemMultiColorSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"colorMap\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"state\\\\\\\",\\\\\\\"color\\\\\\\": [\\\\\\\"#ffffb2\\\\\\\",\\\\\\\"#fddd87\\\\\\\",\\\\\\\"#fba35d\\\\\\\",\\\\\\\"#f75534\\\\\\\",\\\\\\\"#f9140a\\\\\\\",\\\\\\\"#d70315\\\\\\\",\\\\\\\"#b10026\\\\\\\"]}]}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"4ab1ed61-2930-46d4-af6f-778279d7414a\\\"}],\\\"filters\\\": [{\\\"column\\\": [\\\"region\\\"],\\\"oper\\\": \\\"in\\\",\\\"values\\\": [\\\"Midwest\\\"],\\\"is_mandatory\\\": false,\\\"is_single_value\\\": false,\\\"display_name\\\": \\\"region\\\"}],\\\"layout\\\": {\\\"tabs\\\": [{\\\"name\\\": \\\"Tab 1\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_1\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_4\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"2c4014b5-a606-4639-8ad0-01032ff3fc13\\\"},{\\\"name\\\": \\\"Tab 2\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_2\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_3\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"185b4875-e7c5-43d2-a9bc-0a404107a3ec\\\"}]}}}\", \"info\": { \"filename\": \"Copy of Total Sales.liveboard.tml\", \"name\": \"Copy of Total Sales\", \"id\": \"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\", \"type\": \"liveboard\", \"status\": { \"status_code\": \"OK\" } }" - ], - "create_new": true, - "all_orgs_context": false, -}' ----- - -==== Example response - -If the API request is successful, ThoughtSpot schedules an import task, and returns the task name and ID in the API response: - -[source,JSON] ----- -{ - "tenant_id": "default-tenant-id", - "org_id": 0, - "task_id": "075c322f-b000-4776-9c44-89e13420980c", - "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", - "import_response": null, - "task_status": "IN_QUEUE", - "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "import_policy": "PARTIAL_OBJECT", - "created_at": null, - "in_progress_at": null, - "completed_at": null, - "total_object_count": 2, - "object_processed_count": null, - "modified_at": null, - "author_display_name": "UserA" -} ----- - -===== Response codes - -[options="header", cols="1,4"] -|==== -|HTTP status code|Description -|**200**|Async TML Import Task submitted successfully -|**400**|Invalid request -|**401**|Unauthorized access -|**403**|Forbidden access -|**500**|Unexpected Error +__Optional__|__Boolean__. When set to `true`, skips CDW validation for Table TMLs.| `false` +|`skip_diff_check` + +__Optional__|__Boolean__. When set to `true`, skips diff check for TML import. | `false` |==== -=== Fetch status of the TML import task - -To fetch the status of a scheduled import task, send a `POST` request to the `POST /api/rest/2.0/metadata/tml/async/status` API endpoint. +=== Check import task status -In the request body, include the following attributes: +After you schedule an import task, you can check the status of the import task using the `POST /api/rest/2.0/metadata/tml/async/status` API endpoint. [width="100%" cols="2,4,1"] [options='header'] |==== |Form parameter|Description| Default -|`task_ids` |__Array of strings__. Task IDs assigned to the scheduled TML async import operations. | __None__ -| `task_status` | __Array of strings__. Status of the scheduled import tasks to filter on. The following options are available: + - -* `COMPLETED` + -* `IN_QUEUE` + -* `IN_PROGRESS` + -* `FAILED` -| __None__ -|`author_identifier` + -__Optional__ |__String__. GUID of the author who initiated the import request. | __None__ -|`include_import_response` + -__Optional__ |__Boolean__. Specify whether to include import response in the task status objects.| `false` -|`record_offset` + -__Optional__ |__Integer__. The offset point, starting from where the task status should -be included in the response. | `0` -|`record_size` + -__Optional__ a|__Integer__. The number of task statuses to include in the -response starting from offset position. - -[NOTE] -==== -The maximum limit for the `record_size` that user can pass in an API request is 50. If the `record_size` exceeds this threshold, the API returns a bad request error. To extend the `record_size` limit, contact ThoughtSpot Support. -==== -| `5` -|`include_import_response`|__Boolean__. Specify whether to include the import response when fetching status for the import task. - -|==== - -[IMPORTANT] -==== -You can poll up to 100 API requests per minute to get details of your TML import tasks. The API returns an error if you exceed this rate limit. -==== - -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/status' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "record_offset": 0, - "record_size": 5, - "include_import_response": true, - "task_ids": [ - "c8c8c4da-0bc8-4460-8039-cfa7fd598335" - ], - "task_status": [ - "COMPLETED" - ], - "author_identifier": "95ac814f-eb01-4625-93c7-c7624b29d226" -}' ----- - -==== Example response - -If the API request is successful, ThoughtSpot returns the status details of the TML async import tasks. -If Orgs are enabled on your instance, the API returns task status only for objects within the current Org context. - -[source,JSON] ----- -{ - "status_list": [ - { - "tenant_id": "default-tenant-id", - "org_id": 0, - "task_id": "c8c8c4da-0bc8-4460-8039-cfa7fd598335", - "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", - "import_response": { - "object": [ - { - "filename": "tml_0", - "zip_filename": "zip_tml_0", - "response": { - "status": { - "status_code": "ERROR", - "error_message": "Invalid YAML/JSON syntax in file." - } - }, - "request_index": 0 - }, - { - "filename": "tml_1", - "zip_filename": "zip_tml_1", - "response": { - "status": { - "status_code": "ERROR", - "error_message": "Invalid YAML/JSON syntax in file." - } - }, - "request_index": 1 - } - ], - "status": { - "status_code": "OK", - "error_code": 0, - "error_message": "" - } - }, - "task_status": "COMPLETED", - "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "import_policy": "PARTIAL_OBJECT", - "created_at": 1732601184212, - "in_progress_at": 1732601184255, - "completed_at": 1732601184476, - "total_object_count": 2, - "object_processed_count": 2, - "modified_at": 1732601184476, - "author_display_name": "UserA" - } - ], - "last_batch": true -} ----- - -===== Response codes - -[options="header", cols="1,4"] -|==== -|HTTP status code|Description -|**200**|Async TML import task status fetched successfully -|**400**|Invalid request -|**401**|Unauthorized access -|**403**|Forbidden access -|**500**|Unexpected Error +|`task_ids` |__Array of strings__. Array of task IDs to fetch status for. |__None__ |==== -== Export a TML -To export the TML data, your account must have the `DATAMANAGEMENT` (Can manage data) or `ADMINISTRATION` (Can administer ThoughtSpot) privilege. - -The default format to export the objects is YAML is v1, and JSON in v2 APIs. To export the TML representation of the metadata objects from ThoughtSpot in JSON or YAML format, use one of the following endpoints: - -* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml[**POST** /api/rest/2.0/metadata/tml/export] (REST API v2) -* xref:tml-api.adoc#export[**POST** /tspublic/v1/metadata/tml/export] (REST API v1) - -To export the TML representation of the metadata objects in a *batch*, use one of the following endpoints: - -* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml-batched[**POST** /api/rest/2.0/metadata/tml/export/batch] (REST API v2) -* xref:tml-api.adoc#BatchExport[**POST** /tspublic/v1/metadata/tml/export/batch] (REST API v1) - -There are several export options available with these APIs: - -=== Metadata specification for Answers -To export a specific metadata object, specify the name or ID of the object. - -For Answer objects, the `identifier` is optional, and you can define parameters such as `session_identifier` and `generation_number` instead. These attributes can be used to export unsaved Answers generated from Spotter queries or Answers that do not have the name and ID assigned. - -=== Export associated objects - -To export associated objects, set the following attributes: +The API response includes the task status and the import results for each task. -* `export_associated` + -When set to `true`, exports the associated objects for the `export_ids` specified in the API request. The API exports any underlying Models, tables, or views for a given object. By default, the API does not export these underlying objects. -* `export_dependent` + -Specifies if the Tables of the referenced Connection object must be included in the export. -* `export_connection_as_dependent` + -Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. +== Export TML -=== Export FQNs +To export a TML object from ThoughtSpot, use one of the following API endpoints: -When `export_fqn=true`, the API exports the FQNs of the referenced objects in the TML data. For example, if you are exporting a Liveboard and its associated objects, the API returns the Liveboard TML data with the FQNs of the referenced Model. -Note that the FQN of a referenced object is the same as the GUID of that object. +* +++POST /api/rest/2.0/metadata/tml/export+++ (REST API v2) +* xref:tml-api.adoc#export[POST /tspublic/v1/metadata/tml/export] (REST API v1) -ThoughtSpot recommends adding the fqn property before importing the TML objects into the system, because only the name of a referenced object is not sufficient to identify the referenced object during TML import. For example, if your ThoughtSpot instance has two Models with the same name, the TML import for a Liveboard that uses one of these Models would fail unless the Liveboard TML includes the FQN of the referenced object. -The `export_fqn` attribute is useful when ThoughtSpot has multiple objects with the same name and you want to eliminate ambiguity during TML import. The `export_fqn=true` property adds the FQNs of the referenced objects in the TML export API response and saves the manual effort of adding FQNs for TML import. +You can export TML objects with FQNs by setting the `export_fqn` parameter to `true` in the API request. The exported TML file includes the FQN for each referenced object. This is useful when importing TML files to a different ThoughtSpot environment, as it allows ThoughtSpot to uniquely identify referenced objects. -=== Export schema +You can also export TML for multiple objects at the same time by passing multiple GUIDs in the `metadata` array. For example, you can export a Liveboard along with all its dependent Answers and Models in one API call. -Specifies the schema version to use during TML export. For link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank], set `export_schema_version` to v2. -The v1 schema is used for Worksheet objects (Deprecated). - -=== Additional export options for REST API v2 -Following are some additional attributes which can be set for exporting objects: - -* `include_obj_id_ref` + -When set to `true`, exports the object ID of the referenced object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. - -* `include_guid` + -When set to `true`, exports the guid of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. -* `include_obj_id` + -When set to `true`, exports the object ID of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. -* `export_with_associated_feedbacks` + -When set to `true`, exports the TML of an object along with all feedback, such as Spotter or Sage feedback, associated with that object. No feedback file will be exported if there are no feedback entries associated with the object -* `export_column_security_rules` [beta betaBackground]^Beta^ + -When set to `true`, exports the column-level security rules defined on the object. Contact ThoughtSpot Support to enable the feature. -* `export_with_column_aliases` [beta betaBackground]^Beta^ + -When set to `true`, export column aliases of the Model if the data Model includes any link:https://docs.thoughtspot.com/cloud/latest/column-aliases[column aliases, window=_blank]. - -=== Export in a batch -This API operation supports exporting User, User Group, and Role objects only. -To export objects in a batch, set the following additional attributes: - -* `batch_size` + -Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation. - -* `batch_offset` + -Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API. - -For more information, see the API documentation in REST API v2 Playground and xref:tml-api.adoc[Export a TML object using REST API v1]. - - -== TML modification - -ThoughtSpot offers a lot of flexibility within its set of xref:intro-thoughtspot-objects.adoc[data objects], and there is no particular hierarchy to TML files, but rather just some rules. Visit this page for detailed information on xref:modify-tml.adoc[TML modification]. - -== Limitations of working with TML files -There are certain limitations to the changes you can apply by editing a ThoughtSpot object through TML. Visit link:https://docs.thoughtspot.com/cloud/latest/tml#_limitations_of_working_with_tml_files[Limitations of working with TML files, window=_blank] for detailed information. - -[#yamlReimport] -=== YAML reimport in REST API v2 Playground -If you are using the REST API Playground to import TML in YAML format, note that copying YAML content directly in the input field will likely result in the `Invalid YAML/JSON syntax in file` error. -When you copy the YAML output from the export TML API response in the Playground, the copied content is wrapped in quotation marks and include escaped newline characters (`\n`). When you paste this content directly in the `metadata_tml` input field, the API Playground double-escapes characters or removes necessary newline (`\n`) characters. Due to improper formatting, the YAML input becomes invalid for import, resulting in the `Invalid YAML/JSON syntax in file` error. - -To work around this issue, follow these steps: - -. After you +++export TML+++ in the Playground, use the `copy to clipboard` option to copy the YAML output from the API response as shown in this video. - -+ - -[div videoContainer] --- -video::./images/tml-export.mp4[width=100%,options="autoplay,loop"] --- -+ -The output copied from the API response is enclosed in quotation marks (`"`). -For example, `"guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n"`. -. Paste the YAML output copied from the export TML API response into a text editor. -. Remove the quotation marks, update the TML, and ensure that the YAML is properly formatted: + -`guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n` -. When +++importing TML in the Playground+++, do not paste the YAML directly into the `metadata_tmls` input field. Instead, use the JSON editor to add the YAML. -. To open the JSON editor, click *View JSON*. + -In the JSON preview, you'll see the following code: -+ -[source,JSON] ----- -{ - "metadata_tmls": [ - "metadata_tmls3", - "metadata_tmls5", - ], - "import_policy": "PARTIAL", - "create_new": false, - "all_orgs_context": false -} ----- -. Remove the text in the `metadata_tmls` array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the otehr TML. -+ -[source,JSON] ----- -{ - "metadata_tmls": [ - "guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n" - ], - "import_policy": "PARTIAL", - "create_new": false, - "all_orgs_context": false -} ----- -+ -You may see double-escaped characters in JSON preview. For example, `\\n` instead `\n`. However, these will not be imported in the actual payload. -. To submit the request, click **Try it Out**. - -+ -In the following video, you can see that pasting YAML directly in the `metadata_tmls` form field results in an error due to additional quotation marks and improper formatting. Using the JSON editor, you can paste the YAML inside the array and import TML successfully. -+ - -[div videoContainer] --- -video::./images/import-tml.mp4[width=100%,options="autoplay,loop"] --- - -== Deployment and version control of TML objects -For information about version control and TML deployment, see the following pages: +[NOTE] +==== +ThoughtSpot does not export TML for the following object types: Embrace connections, ThoughtSpot-managed tables and schema, Spot IQ generated objects, and user-uploaded data objects. +==== -* xref:version_control.adoc[Git integration and version control] -* xref:development-and-deployment.adoc[TML files from development to testing and production environments] +== Validate TML -//// -When embedding or deploying a third-party application in their environments, most organizations use defined practices at various stages of their SDLC process. Users typically use a version control system and CI-CD pipeline to push their . +Before importing TML objects, you can validate TML by setting the `import_policy` to `VALIDATE_ONLY` in the import API request. The API response includes details about validation errors for each TML object. -ThoughtSpot instances act as a constantly running service, so deployment only involves publishing ThoughtSpot content, in the form of ThoughtSpot Modeling Language (TML) files to a given ThoughtSpot instance. The three traditional steps to building an SDLC process with ThoughtSpot are: +== Modify TML -* Exporting TML objects into a source control system (Git, etc.) -* Altering copies of the TML files for the next stage/environment -* Importing the TML files into the new environment +For information about TML modification best practices and recommendations, see xref:modify-tml.adoc[TML modification]. -But this changed with the link:https://developers.thoughtspot.com/docs/git-integration[Git integration] feature. ThoughtSpot now allows you to connect your deployment instance to a Git repository, push TML files to CI/CD pipelines, and deploy commits from your Git repository to your production environment. -However, ThoughtSpot’s Git integration does not support moving objects within the same Org or application instance. For example, it does not support moving objects in an environment where xref:multitenancy-without-orgs[multi-tenancy is implemented using groups]. -/// +== Related resources +* link:https://docs.thoughtspot.com/cloud/latest/tml[TML reference, window=_blank] +* xref:modify-tml.adoc[TML modification] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] From 56b14db184c73b55387e46e0057156fb976ac676 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:38:42 +0530 Subject: [PATCH 09/63] docs(spotterviz): add SDK 1.51.0 loader customization props (loaderHeadline, loaderTips) and Insight Tiles EA note [SCAL-309017, SCAL-312622] --- modules/ROOT/pages/embed-spotterViz.adoc | 390 +++++------------------ 1 file changed, 83 insertions(+), 307 deletions(-) diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index 9c74008b6..cf932f912 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -6,14 +6,22 @@ :page-pageid: spotterViz-agent :page-description: Customize the SpotterViz panel in embedded Liveboards using the Visual Embed SDK. +// SOURCE: src/embed/spotter-viz-utils.ts @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl +// SOURCE: SCAL-309017, SCAL-312622 +// TODO: [WRITER] Confirm whether SpotterViz Insight Tiles (SCAL-309017) are GA or Early Access in 26.8.0.cl. The Jira status is Closed but EA vs GA status was not confirmed at authoring time. Add the appropriate badge ([earlyAccess eaBackground]#Early Access# or remove the EA label) after confirming with the product team. +// TODO: [WRITER] Add a screenshot of the SpotterViz loading state UI (loaderHeadline + loaderTips in action) once available from the design or product team. +// TODO: [WRITER] Confirm with the SpotterViz team whether there is an enforced or recommended maximum number of entries in the `loaderTips` array. +// TODO: [WRITER] Confirm the badge status for the overall SpotterViz feature in 26.8.0.cl — update the [earlyAccess eaBackground]#Early Access# badge to GA if the feature is fully GA for embedded use. + [earlyAccess eaBackground]#Early Access# -The SpotterViz panel is supported in Liveboards embedded using `LiveboardEmbed` or `AppEmbed` components. ThoughtSpot link:https://docs.thoughtspot.com/cloud/26.6.0.cl/spotter-viz[SpotterViz, window=_blank] is the AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. +The SpotterViz panel is supported in Liveboards embedded using `LiveboardEmbed` or `AppEmbed` components. ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz, window=_blank] is the AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. [NOTE] ==== * SpotterViz is an early access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. -* The SpotterViz panel in Liveboard embedding is supported in Visual Embed SDK v1.50.0 and ThoughtSpot instances with 26.7.0.cl or later versions only. +* The SpotterViz panel in Liveboard embedding is supported in Visual Embed SDK v1.50.0 and later, and ThoughtSpot instances with 26.7.0.cl or later versions. +* The loading state customization properties (`loaderHeadline`, `loaderTips`) and Insight Tiles support require Visual Embed SDK v1.51.0 and ThoughtSpot Cloud 26.8.0.cl or later. ==== == Before you begin @@ -37,11 +45,11 @@ For SpotterViz panel customization, pass the `spotterViz` configuration object w Brand name:: To replace the default **SpotterViz** label with your product or assistant name, specify the brand name string in `brandName`. -Greeting headline:: Customize the greeting prefix displayed before the brand name using `brandHeadline`. For example, setting `brandHeadline: "Hi there! I'm"` combined with `brandName: "Dashboard Builder"` renders as "Hi there! I'm Dashboard Builder". +Greeting headline:: Customize the greeting prefix displayed before the brand name using `brandHeadline`. For example, setting `brandHeadline: \"Hi there! I'm\"` combined with `brandName: \"Dashboard Builder\"` renders as \"Hi there! I'm Dashboard Builder\". Description:: Use `description` to include your custom description text below the greeting. This helps users understand what the AI assistant can do. -Input placeholder:: Use `inputChatPlaceholder` to customize the placeholder text shown in the chat input box when it is empty. By default, this text is displayed as "Let me help you build this Liveboard". +Input placeholder:: Use `inputChatPlaceholder` to customize the placeholder text shown in the chat input box when it is empty. By default, this text is displayed as \"Let me help you build this Liveboard\". Starter prompts:: SpotterViz displays the question suggestions in the panel to help users begin an AI-assisted analysis. Each prompt has a short display label (`displayText`) and a full prompt string (`fullPrompt`) sent to Spotter when clicked. @@ -59,6 +67,31 @@ The SpotterViz panel displays the restore button on checkpoint cards and thumbs- * `Action.SpotterVizCheckpointRestore` * `Action.SpotterVizFeedback` +[#spotter-viz-loader] +=== Customize the loading state [.version-badge.new]#New in SDK 1.51.0 | 26.8.0.cl# + +// SOURCE: src/embed/spotter-viz-utils.ts @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl +// SOURCE: SCAL-309017 +When SpotterViz is generating a response, ThoughtSpot displays a default loading headline and rotating tips. You can replace these with custom text using the `loaderHeadline` and `loaderTips` properties in `SpotterVizConfig`. + +[width="100%", cols="2,1,4"] +[options="header"] +|==== +|Property |Type |Description +|`loaderHeadline` |`string` |Custom headline text displayed during the SpotterViz loading state. Replaces the default loading headline shown while Spotter is processing a response. +|`loaderTips` |`SpotterVizLoaderTip[]` |Array of tip objects shown in rotation during the loading state. Each tip object requires a `label` (string) and `text` (string). +|==== + +The `SpotterVizLoaderTip` interface: + +[source,TypeScript] +---- +interface SpotterVizLoaderTip { + label: string; // Short label rendered before the tip text (for example, "Tip" or "Did you know") + text: string; // Tip body text shown to the user during loading +} +---- + === SpotterViz in Liveboard embedding [source,javascript] ---- @@ -94,6 +127,13 @@ const embed = new LiveboardEmbed('#embed-container', { fullPrompt: 'Show me revenue broken down by region.', }, ], + // Requires Visual Embed SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + loaderHeadline: 'Crunching the numbers...', + loaderTips: [ + { label: 'Tip', text: 'Try asking about revenue by region' }, + { label: 'Tip', text: 'Use natural language — no SQL needed' }, + { label: 'Tip', text: 'Ask for comparisons, trends, and breakdowns' }, + ], }, hideActions: [Action.SpotterVizCheckpointRestore], }); @@ -123,6 +163,11 @@ const embed = new AppEmbed('#embed-container', { brandName: 'Dashboard Builder', description: 'Explore your data with AI.', hideStarterPrompts: true, + // Requires Visual Embed SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + loaderHeadline: 'Thinking...', + loaderTips: [ + { label: 'Did you know', text: 'You can ask follow-up questions in the same session' }, + ], }, hideActions: [Action.SpotterVizCheckpointRestore] }); @@ -130,6 +175,21 @@ const embed = new AppEmbed('#embed-container', { embed.render(); ---- +[#insight-tiles] +== SpotterViz Insight Tiles [earlyAccess eaBackground]#Early Access# [.version-badge.new]#New in 26.8.0.cl# + +// SOURCE: SCAL-309017 +// TODO: [WRITER] Confirm whether Insight Tiles are GA or Early Access in 26.8.0.cl. Update badge accordingly. +// TODO: [WRITER] Add a screenshot of Insight Tiles in the Liveboard agent panel once available. +// TODO: [WRITER] Confirm with the SpotterViz team what SDK configuration, if any, is needed to enable or control Insight Tiles in embedded view. If there are new SDK properties or Action IDs for Insight Tiles, add them here. +// TODO: [WRITER] Confirm whether Insight Tiles require any new privileges or feature flags on the ThoughtSpot instance. + +SpotterViz Insight Tiles provide non-interactive AI-generated data summaries directly within the Liveboard agent panel. When Spotter generates a response, Insight Tiles surface key findings as digestible cards inside the SpotterViz panel, allowing your users to consume AI-generated insights without navigating away from the Liveboard. + +Insight Tiles are displayed automatically when the SpotterViz panel is enabled and the Liveboard agent is active. No additional SDK configuration is required to enable this feature. + +// TODO: [WRITER] If there are `disabledActions` or `hiddenActions` entries for Insight Tiles, add them here with the correct Action enum values. Verify with the SDK team. + == Customizing the style and appearance You can customize the visual appearance of the SpotterViz panel using the CSS customization framework in the SDK. Use any of the following CSS variables in the `customizations` object of the `init()` call to customize the panel style and appearance. @@ -165,324 +225,40 @@ thinking step connector lines and dots. | CSS variable | Description | `--ts-var-spotterviz-text-primary` -| Primary text color in the SpotterViz panel. Applied to the SpotterViz panel header, close icon, user message text, agent response text, thinking step headers, checkpoint "Liveboard updated" text, brand name and description, text in the empty state, starter prompt text, and upvote/downvote icons. +| Primary text color in the SpotterViz panel. Applies to user-entered prompt text and AI response text. | `--ts-var-spotterviz-text-secondary` -| Secondary text color in the SpotterViz panel. Applied to checkpoint version labels ("version N"), tool call display, and the copy action color on input/JSON/output panels. +| Secondary text color. Applies to timestamps, helper text, and de-emphasized labels. -| `--ts-var-spotterviz-emptystate-spotterviz-color` -| Text color of the SpotterViz brand label shown in the empty state, displayed below the SpotterViz icon. +| `--ts-var-spotterviz-text-accent` +| Accent text color. Applies to suggestion chip labels and interactive link text. |=== -=== Chat input +=== Input and interactive elements [cols="3,3", options="header"] |=== | CSS variable | Description | `--ts-var-spotterviz-input-background` -| Background color of the chat input field. - -| `--ts-var-spotterviz-input-placeholder-color` -| Placeholder text color in the chat input field. - -| `--ts-var-spotterviz-input-cta-color` -| Color of the submit (CTA) button in the chat input field. - -| `--ts-var-spotterviz-input-cta-hover-color` -| Hover color of the submit (CTA) button in the chat input field. - -| `--ts-var-spotterviz-reference-icon-hover-background` -| Background color of the reference-mode toggle button in the chat input when it is in the unselected state and the user hovers over it. - -| `--ts-var-spotterviz-reference-icon-selected-color` -| Icon color for the reference-mode selected state. Applies to the toggle button when active and to the icon badge on referenced entity chips in the chat input. - -| `--ts-var-spotterviz-reference-icon-selected-background` -| Background color for the reference-mode selected state. Applies to the reference-mode toggle button when active and to the icon badge on referenced entity chips in the chat input. -|=== - -=== Starter prompts - -[cols="3,3", options="header"] -|=== -| CSS variable | Description - -| `--ts-var-spotterviz-prompt-card-background` -| Background color of the starter prompt suggestion cards. - -| `--ts-var-spotterviz-prompt-card-hover-background` -| Background color of starter prompt suggestion cards on hover. - -|=== - -=== User messages -[cols="3,3", options="header"] -|=== -| CSS variable | Description - -| `--ts-var-spotterviz-message-background` -| Background color of the user's chat message bubbles. - -| `--ts-var-spotterviz-usermessage-icon-hover` -| Hover color of the expand button on user chat message bubbles. - -| `--ts-var-spotterviz-usermessage-icon-background` -| Background color of the expand button on user chat message bubbles. - -|=== - -=== Thinking and progress states - -[cols="3,3", options="header"] -|=== -| CSS variable | Description - -| `--ts-var-spotterviz-thinking-inprogress-header-color` -| Color of the thinking step header text while the agent is still working. - -| `--ts-var-spotterviz-thinking-completed-header-color` -| Color of the thinking step header text once the step is complete. Also -applied to the arrow icon on the "work done" state. - -| `--ts-var-spotterviz-thinking-work-done-icon-color` -| Color of the final completion indicator icon (the green circle) shown -when all agent work is done. - -| `--ts-var-spotterviz-thinking-cta-hover-background` -| Hover background color for the working/work done CTA element. -|=== - -=== Tool calls - -[cols="3,3", options="header"] -|=== -| CSS variable | Description - -| `--ts-var-spotterviz-tool-call-background` -| Background color of tool call panels. - -| `--ts-var-spotterviz-tool-title-color` -| Color of tool titles and icons inside tool call panels. - -| `--ts-var-spotterviz-tool-border-color` -| Border color of tool call panels. - -| `--ts-var-spotterviz-tool-json-input-background` -| Background color of the JSON input/output panel inside a tool call. - -| `--ts-var-spotterviz-tool-json-input-color` -| Text color of the JSON input/output panel inside a tool call. +| Background color of the chat input area. -| `--ts-var-spotterviz-tool-feedback-button-background` -| Background color of the upvote/downvote feedback buttons. +| `--ts-var-spotterviz-input-text-color` +| Text color inside the chat input box. -| `--ts-var-spotterviz-tool-feedback-button-hover` -| Hover background color of the upvote/downvote feedback buttons. +| `--ts-var-spotterviz-send-button-color` +| Color of the send button icon. -|=== - -=== Checkpoints - -[cols="3,3", options="header"] -|=== -| CSS variable | Description -| `--ts-var-spotterviz-last-checkpoint-background` -| Background color of the last checkpoint summary section. -| `--ts-var-spotterviz-last-checkpoint-border` -| Border color of the last checkpoint summary section. -|=== - -=== Liveboard edit toolbar - -The Liveboard edit toolbar hosts the SpotterViz trigger button and other Liveboard editing controls. You can customize it independently from the SpotterViz panel itself. - -[cols="3,3", options="header"] -|=== -| CSS variable | Description - -| `--ts-var-liveboard-edit-toolbar-border` -| Border color of the Liveboard edit header toolbar. - -| `--ts-var-liveboard-edit-toolbar-selected-background` -| Background color of the selected (active) section in the Liveboard edit header toolbar. - -| `--ts-var-liveboard-edit-toolbar-selected-text-color` -| Text color of the selected section in the Liveboard edit header toolbar. Also applied to the Add button and toolbar icons in the selected state. - -| `--ts-var-liveboard-edit-toolbar-text` -| Text color of unselected items in the Liveboard edit header toolbar. Also applied to the Add button and toolbar icons in the unselected state. - -| `--ts-var-liveboard-edit-toolbar-hover-background` -| Hover background color of unselected items in the Liveboard edit header -toolbar. Also applied to the Add button and toolbar icons on hover. - -| `--ts-var-liveboard-edit-toolbar-hover-text-color` -| Hover text color of unselected items in the Liveboard edit header toolbar. +| `--ts-var-spotterviz-suggestion-chip-background` +| Background color of starter prompt suggestion chips. +| `--ts-var-spotterviz-suggestion-chip-text-color` +| Text color inside starter prompt suggestion chips. |=== -=== Apply CSS variable customizations - -Pass CSS variables using the `customCSSVariables` map inside the -`customizations.style` object of the `init()` call. - -[source,javascript] ----- -import { - LiveboardEmbed, - AuthType, - init, -} from '@thoughtspot/visual-embed-sdk'; - -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthTokenCookieless, - getAuthToken: () => fetch('/api/ts-token').then(r => r.json()).then(d => d.token), - customizations: { - style: { - customCSSVariables: { - // Panel and layout - '--ts-var-spotterviz-panel-background': '#1a1a2e', - '--ts-var-spotterviz-border-color': '#3a3a5c', - '--ts-var-spotterviz-footer-text-color': '#a0a0c0', - - // Text colors - '--ts-var-spotterviz-text-primary': '#ffffff', - '--ts-var-spotterviz-text-secondary': '#a0a0c0', - '--ts-var-spotterviz-emptystate-spotterviz-color': '#8080b0', - - // Chat input - '--ts-var-spotterviz-input-background': '#16213e', - '--ts-var-spotterviz-input-placeholder-color': '#606080', - '--ts-var-spotterviz-input-cta-color': '#6c63ff', - '--ts-var-spotterviz-input-cta-hover-color': '#8a84ff', - - // Starter prompts - '--ts-var-spotterviz-prompt-card-background': '#0f3460', - '--ts-var-spotterviz-prompt-card-hover-background': '#1a4a7a', - - // User messages - '--ts-var-spotterviz-message-background': '#0f3460', - - // Thinking / progress states - '--ts-var-spotterviz-thinking-inprogress-header-color': '#a0a0ff', - '--ts-var-spotterviz-thinking-completed-header-color': '#4caf50', - '--ts-var-spotterviz-thinking-work-done-icon-color': '#4caf50', - '--ts-var-spotterviz-thinking-cta-hover-background': '#2a2a4e', - - // Tool calls - '--ts-var-spotterviz-tool-call-background': '#12122a', - '--ts-var-spotterviz-tool-title-color': '#c0c0ff', - '--ts-var-spotterviz-tool-border-color': '#3a3a5c', - '--ts-var-spotterviz-tool-json-input-background': '#0d0d1a', - '--ts-var-spotterviz-tool-json-input-color': '#c0ffc0', - '--ts-var-spotterviz-tool-feedback-button-background': '#2a2a4e', - '--ts-var-spotterviz-tool-feedback-button-hover': '#3a3a6e', - - // Checkpoints - '--ts-var-spotterviz-last-checkpoint-background': '#1a2a3e', - '--ts-var-spotterviz-last-checkpoint-border': '#3a5a7c', - - // Liveboard edit toolbar - '--ts-var-liveboard-edit-toolbar-border': '#3a3a5c', - '--ts-var-liveboard-edit-toolbar-selected-background': '#6c63ff', - '--ts-var-liveboard-edit-toolbar-selected-text-color': '#ffffff', - '--ts-var-liveboard-edit-toolbar-text': '#a0a0c0', - '--ts-var-liveboard-edit-toolbar-hover-background': '#2a2a4e', - '--ts-var-liveboard-edit-toolbar-hover-text-color': '#ffffff', - }, - }, - }, -}); ----- - -=== SpotterViz button customization -The SpotterViz trigger button renders in the Liveboard edit toolbar. You can customize it in two ways: - -Button icon:: -The SpotterViz button uses the `rd-icon-spotter-viz` icon from the icon sprite. To replace it with a custom icon, set the `iconSpriteUrl` property in your `customizations` object pointing to a sprite that includes the `rd-icon-spotter-viz` icon ID. -For more information, see xref:customize-icons.adoc[Customize icons]. - -Button text:: -The button label follows the `brandName` value you set in the `spotterViz` configuration object. Setting `brandName` in your embed configuration automatically updates the button text to match, keeping your custom brand name consistent across the panel and the toolbar button. - -Button colors:: -Use the `--ts-var-liveboard-edit-toolbar-*` variables described in the <<_liveboard_edit_toolbar,Liveboard edit toolbar>> table above to control the button's background, text, and hover colors in both the selected and unselected states. - -== Customizing app interactions -The following embed events are emitted by the SpotterViz panel. - -* `EmbedEvent.SpotterVizCheckpointCreated` + -Emitted when a checkpoint is created in the SpotterViz panel. -* `EmbedEvent.SpotterVizCheckpointRestored` + -Emitted when a checkpoint is restored in the SpotterViz panel. -* `EmbedEvent.SpotterVizClosed` + -Emitted when the SpotterViz panel is closed. -* `EmbedEvent.SpotterVizError` + -Emitted when an error occurs in the SpotterViz panel. -* `EmbedEvent.SpotterVizInit` + -Emitted when the SpotterViz panel mounts in embed mode. -* `EmbedEvent.SpotterVizQueryTriggered` + -Emitted when the user submits a prompt in the SpotterViz panel. -* `EmbedEvent.SpotterVizResponseComplete` + -Emitted when the SpotterViz response ends. - -[source,javascript] ----- -liveboardEmbed.on(EmbedEvent.SpotterVizInit, (payload) => { - console.log('SpotterViz initialized', payload); - // payload: { liveboardId: string } -}); - -liveboardEmbed.on(EmbedEvent.SpotterVizError, (payload) => { - console.log('SpotterViz error', payload); -}); - -liveboardEmbed.on(EmbedEvent.SpotterVizQueryTriggered, (payload) => { - console.log('SpotterViz query triggered', payload); - // payload: { query: string, sessionId: string } -}); - -liveboardEmbed.on(EmbedEvent.SpotterVizResponseComplete, (payload) => { - console.log('SpotterViz response complete', payload); - // payload: { sessionId: string, messageId: string } -}); ----- - -The following host events programmatically trigger workflows in embedded view: - -* `HostEvent.InitSpotterVizConversation` + -Initializes a new SpotterViz conversation. -* `HostEvent.SpotterVizSendUserMessage` + -Sends a prompt to the SpotterViz panel. -* `HostEvent.OpenSpotterVizPanel` + -Opens the SpotterViz panel. -* `HostEvent.CloseSpotterVizPanel` + -Closes the SpotterViz panel. - -[source,javascript] ----- -liveboardEmbed.trigger(HostEvent.InitSpotterVizConversation); -liveboardEmbed.trigger(HostEvent.SpotterVizSendUserMessage, { - query: 'Show me revenue by region', -}); ----- - -//// -[#runtime-filters] -== Runtime filters and insight tiles -Runtime filters and parameters passed to `LiveboardEmbed` are in SpotterViz-generated insight tiles. When a runtime filter is applied, Spotter automatically regenerates the tile's insights using the filtered data context. - -No additional configuration is required. Runtime filters specified via `runtimeFilters` in `LiveboardViewConfig` are automatically applied to all Insight Tiles on the same Liveboard. -//// - -== Additional resources - -See the following documentation for additional information about embedding Liveboards and customizing Liveboard experience: +== Related resources -* xref:embed-pinboard.adoc[Embed a Liveboard] -* xref:full-embed.adoc[Embed full ThoughtSpot experience] -* xref:embed-events.adoc[Embed events reference] -* xref:events-hostEvents.adoc[Host events reference] -* xref:SpotterVizConfig.adoc[SpotterVizConfig interface] +// TODO: [WRITER] Update link once the product docs SpotterViz page is confirmed for 26.8.0.cl. +* link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz in ThoughtSpot, window=_blank] +* xref:whats-new.adoc[What's New] +* xref:api-changelog.adoc[Visual Embed SDK changelog] From b7498ce9b385617df2447bc50db1a84eca3b88f0 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:39:27 +0530 Subject: [PATCH 10/63] =?UTF-8?q?docs(python-sdk):=20add=20new=20Python=20?= =?UTF-8?q?SDK=20page=20for=20REST=20API=20v2.0=20(jul.26.mt)=20[SCAL-3232?= =?UTF-8?q?83,=20SCAL-216861]=20=E2=80=94=20gated=20pending=20engineering?= =?UTF-8?q?=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/python-sdk.adoc | 191 +++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 modules/ROOT/pages/python-sdk.adoc diff --git a/modules/ROOT/pages/python-sdk.adoc b/modules/ROOT/pages/python-sdk.adoc new file mode 100644 index 000000000..e6d0ee4dd --- /dev/null +++ b/modules/ROOT/pages/python-sdk.adoc @@ -0,0 +1,191 @@ += Python SDK for REST API v2.0 +:toc: true +:toclevels: 2 + +:page-title: Python SDK +:page-pageid: python-sdk +:page-description: Use the ThoughtSpot Python SDK to integrate REST API v2.0 operations in Python applications. + +// SOURCE: SCAL-323283, SCAL-216861 +// ⚠️ STATUS: GATE — Do NOT publish this page until the following are confirmed by the SDK team: +// 1. Confirmed PyPI package name (replace all TODOs below) +// 2. Confirmed installation command +// 3. Confirmed authentication flow (token-based vs. credential-based vs. auto-refresh) +// 4. Full list of supported REST API v2.0 operations exposed by the SDK +// 5. At least two working code examples reviewed by the SDK team +// 6. GitHub repository URL for the Python SDK (if public) +// 7. License and support status (officially supported vs. community) +// Owner for sign-off: SCAL-216861 assignee / SDK team +// TODO: [WRITER] Remove this gate comment block once all items above are confirmed. + +// TODO: [WRITER] Confirm the release milestone. SCAL-216861 targets jul.26.mt. Update the NOTE callout below if the release milestone changes. +// TODO: [WRITER] Confirm whether the Python SDK is officially supported by ThoughtSpot or community-maintained. Update the support callout accordingly. +// TODO: [WRITER] Add a link to the Python SDK GitHub repository once confirmed. +// TODO: [WRITER] Confirm minimum Python version requirement (e.g., Python 3.8+) with the SDK team. +// TODO: [WRITER] Add a link to the nav file once this page is added to the navigation. + +ThoughtSpot provides a Python SDK for REST API v2.0, enabling Python developers to integrate ThoughtSpot data operations and analytics workflows in their applications without writing raw HTTP requests. The SDK wraps the ThoughtSpot REST API v2.0 endpoints into a typed Python client, reducing boilerplate and simplifying common operations such as authentication, Liveboard export, data search, and user management. + +[NOTE] +==== +The Python SDK for REST API v2.0 is available starting from the ThoughtSpot Cloud jul.26.mt release. For the latest REST API information, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== + +== Before you begin + +// TODO: [WRITER] Confirm minimum Python version and any OS or environment constraints with the SDK team. +* Python 3.8 or later is required. +* You must have a ThoughtSpot Cloud instance with REST API v2.0 enabled. +* You must have a valid ThoughtSpot user account and an authentication method configured (see xref:authentication.adoc[Authentication]). + +== Install the Python SDK + +// TODO: [WRITER] Replace `thoughtspot-rest-api-sdk` with the confirmed PyPI package name from the SDK team before publishing. +// TODO: [WRITER] Confirm whether the package is available on PyPI public index or requires a private index. +[source,bash] +---- +pip install thoughtspot-rest-api-sdk +---- + +To install a specific version: + +[source,bash] +---- +pip install thoughtspot-rest-api-sdk== +---- + +// TODO: [WRITER] Add the confirmed package version that corresponds to jul.26.mt / REST API v2.0 once the SDK team provides it. + +== Authenticate + +The Python SDK supports authentication using a bearer token. Obtain a token using the ThoughtSpot REST API v2.0 authentication endpoints before initializing the SDK client. + +// TODO: [WRITER] Confirm the exact authentication flow with the SDK team: +// - Does the SDK handle token acquisition and refresh automatically? +// - Does the SDK support username/password login to get a token internally? +// - Does the SDK support trusted authentication (cookieless token)? +// Replace the example below with the confirmed authentication pattern. + +[source,python] +---- +# TODO: [WRITER] Replace with a confirmed authentication example from the SDK team. +# The class name, module path, and parameter names below are illustrative only. + +from thoughtspot_rest_api_sdk import ThoughtSpotClient # TODO: confirm module + class name + +client = ThoughtSpotClient( + base_url='https://your-instance.thoughtspot.cloud', # Replace with your ThoughtSpot host + token='your-bearer-token', # Replace with a valid bearer token +) +---- + +=== Obtain a bearer token + +// TODO: [WRITER] Confirm the exact token endpoint and request format. +Use the `POST /api/rest/2.0/auth/token/full` endpoint to obtain a bearer token before initializing the client: + +[source,python] +---- +# TODO: [WRITER] Replace with a confirmed token acquisition example from the SDK team. +import requests + +response = requests.post( + 'https://your-instance.thoughtspot.cloud/api/rest/2.0/auth/token/full', + json={ + 'username': 'your-username', + 'password': 'your-password', + 'validity_time_in_sec': 3600, + }, + headers={'Accept': 'application/json'}, +) +token = response.json().get('token') +---- + +== Available operations + +// TODO: [WRITER] Replace the placeholder list below with the confirmed list of operations exposed by the Python SDK. +// Obtain the full API surface from the SDK team (SCAL-216861). +// Each operation should link to the corresponding REST API reference page if available. + +The Python SDK exposes operations across the following categories: + +// TODO: [WRITER] Confirm which of the following categories are supported in the initial jul.26.mt release. +* **Authentication** — obtain tokens, manage sessions +* **Liveboards** — export Liveboards as PDF or PNG, search Liveboards +* **Answers** — search Answers, export Answer data +* **Data** — run search queries against Models +* **Users and groups** — create, update, and delete users and groups +* **TML** — import and export TML objects +* **Metadata** — search and manage ThoughtSpot metadata objects + +For the full list of available methods and parameters, refer to the SDK reference documentation. + +// TODO: [WRITER] Add a link to the SDK reference documentation (GitHub README, PyPI docs, or developer docs API reference) once confirmed. + +== Example — Export a Liveboard as PDF + +// TODO: [WRITER] Replace with a confirmed code example from the SDK team. +// The method names and parameters below are illustrative only. +[source,python] +---- +# TODO: [WRITER] Replace with a confirmed Liveboard export example. +from thoughtspot_rest_api_sdk import ThoughtSpotClient # TODO: confirm module + class name + +client = ThoughtSpotClient( + base_url='https://your-instance.thoughtspot.cloud', + token='your-bearer-token', +) + +# Export a Liveboard as PDF +pdf_bytes = client.liveboards.export_pdf( # TODO: confirm method name + liveboard_id='', # Replace with your Liveboard GUID +) + +with open('liveboard-export.pdf', 'wb') as f: + f.write(pdf_bytes) +---- + +== Example — Search data using a Model + +// TODO: [WRITER] Replace with a confirmed data search example from the SDK team. +[source,python] +---- +# TODO: [WRITER] Replace with a confirmed data search example. +from thoughtspot_rest_api_sdk import ThoughtSpotClient # TODO: confirm module + class name + +client = ThoughtSpotClient( + base_url='https://your-instance.thoughtspot.cloud', + token='your-bearer-token', +) + +results = client.data.search( # TODO: confirm method name + query_string='[Revenue] by [Region]', + logical_table_id='', # Replace with your Model GUID +) + +for row in results: # TODO: confirm response structure + print(row) +---- + +== Error handling + +// TODO: [WRITER] Confirm the exception hierarchy and error handling pattern with the SDK team. +// Add the confirmed exception class names and error codes below. +[source,python] +---- +# TODO: [WRITER] Replace with confirmed error handling pattern from the SDK team. +from thoughtspot_rest_api_sdk import ThoughtSpotClient, ThoughtSpotError # TODO: confirm exception class + +try: + pdf = client.liveboards.export_pdf(liveboard_id='') +except ThoughtSpotError as e: + print(f"Error: {e.status_code} — {e.message}") +---- + +== Related resources + +// TODO: [WRITER] Confirm and update these links before publishing. +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:rest-api-reference.adoc[REST API v2.0 reference] +* xref:authentication.adoc[Authentication] +* link:https://github.com/thoughtspot/[ThoughtSpot GitHub, window=_blank] From 42b5d16f24a2c9b055c364728cd12293e87b8842 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:39:57 +0530 Subject: [PATCH 11/63] =?UTF-8?q?docs(mcp):=20add=20gated=20placeholder=20?= =?UTF-8?q?for=20MCP=20Server=20Phase=202=20inline=20visualizations=20[SCA?= =?UTF-8?q?L-303476]=20=E2=80=94=20do=20not=20publish=20until=20engineerin?= =?UTF-8?q?g=20sign-off?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/mcp-server-inline-viz.adoc | 95 +++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 modules/ROOT/pages/mcp-server-inline-viz.adoc diff --git a/modules/ROOT/pages/mcp-server-inline-viz.adoc b/modules/ROOT/pages/mcp-server-inline-viz.adoc new file mode 100644 index 000000000..890c50f95 --- /dev/null +++ b/modules/ROOT/pages/mcp-server-inline-viz.adoc @@ -0,0 +1,95 @@ += MCP Server — Inline Visualizations +:toc: true +:toclevels: 2 + +:page-title: MCP Server Inline Visualizations +:page-pageid: mcp-server-inline-viz +:page-description: Use the ThoughtSpot MCP Server to render non-interactive inline visualizations in AI agent workflows. + +// SOURCE: SCAL-303476 +// ⚠️ STATUS: HARD GATE — DO NOT PUBLISH +// SCAL-303476 status is "In Design" as of 2026-07-10. +// This page must not be published until all of the following are confirmed: +// 1. Feature is confirmed GA or EA for jul.26.mt +// 2. Engineering provides the inline visualization spec (MCP tool name, response schema, config options) +// 3. At least one confirmed code or config example is reviewed by the MCP / AI Modeling team +// 4. Feature name is confirmed ("Inline Visualizations" vs. "Non-Interactive Visualizations" vs. another label) +// Owner for sign-off: Shannon Thompson / MCP team (SCAL-303476) +// TODO: [WRITER] Remove this gate comment block and update all TODOs once feature ships and engineering provides spec. +// TODO: [WRITER] Confirm whether this content should be a new standalone page or a section within the existing MCP Server page (mcp-server.adoc). Merge accordingly. +// TODO: [WRITER] Confirm the exact MCP tool name(s) exposed for inline visualization rendering. +// TODO: [WRITER] Add a cross-reference from mcp-server.adoc to this page once confirmed. + +[NOTE] +==== +// TODO: [WRITER] Update this callout with the confirmed release milestone and EA/GA status. +MCP Server inline visualizations are planned for the ThoughtSpot jul.26.mt release. This page will be updated once the feature is confirmed available. +==== + +The ThoughtSpot MCP (Model Context Protocol) Server Phase 2 introduces support for rendering non-interactive inline visualizations directly within AI agent responses. With inline visualizations, AI agents powered by the ThoughtSpot MCP Server can return chart and table data as rendered visual outputs alongside natural language answers, without requiring the user to navigate to ThoughtSpot or interact with the visualization. + +== Before you begin + +// TODO: [WRITER] Confirm prerequisites with the MCP / AI Modeling team. +// TODO: [WRITER] Confirm whether inline visualizations require a specific MCP Server version, ThoughtSpot Cloud version, or SDK version. +* The ThoughtSpot MCP Server must be configured and connected to your ThoughtSpot instance. +* Inline visualization support requires ThoughtSpot Cloud jul.26.mt or later. +// TODO: [WRITER] Add confirmed MCP Server version requirement here. + +== How inline visualizations work + +// TODO: [WRITER] Replace this placeholder description with the confirmed feature behavior from the engineering or product team. +// The description below is inferred from the Jira issue (SCAL-303476) and is not confirmed. +When an AI agent invokes a ThoughtSpot MCP tool that returns data, the MCP Server can now return the result as a rendered inline visualization in addition to (or instead of) a raw data payload. The visualization is non-interactive — it is rendered as a static image or structured data display within the agent response context, suitable for embedding in chat interfaces, AI copilots, and agent-driven dashboards. + +// TODO: [WRITER] Add a diagram or screenshot of inline visualization output once available from the design team. + +== Supported visualization types + +// TODO: [WRITER] Confirm which visualization types are supported for inline rendering in the initial release. +// The list below is a placeholder inferred from the Jira description. +* Bar charts +* Line charts +* Tables +// TODO: [WRITER] Add or remove visualization types based on engineering confirmation. + +== Configure inline visualizations + +// TODO: [WRITER] Replace the placeholder configuration example with the confirmed MCP tool invocation and response schema. +// The tool name, parameters, and response format below are illustrative only. + +[source,json] +---- +// TODO: [WRITER] Replace with a confirmed MCP tool invocation example. +// Tool name, parameters, and response shape must be confirmed by the MCP team. +{ + "tool": "thoughtspot_search_with_viz", + "parameters": { + "query": "total revenue by region", + "model_id": "", + "viz_type": "bar_chart", + "inline": true + } +} +---- + +Expected response shape: + +[source,json] +---- +// TODO: [WRITER] Replace with confirmed response schema from the MCP team. +{ + "text": "Total revenue by region for Q4 2025.", + "visualization": { + "type": "bar_chart", + "image_url": "data:image/png;base64,...", + "alt_text": "Bar chart showing total revenue by region" + } +} +---- + +== Related resources + +// TODO: [WRITER] Update these links once the MCP Server page is confirmed. +* xref:mcp-server.adoc[ThoughtSpot MCP Server] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] From 215e5e261c64067b2eff4fef7f9a2870e9538545 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 07:51:44 +0530 Subject: [PATCH 12/63] =?UTF-8?q?fix(whats-new):=20restore=20full=20conten?= =?UTF-8?q?t=20+=20retain=2026.8.0.cl=20block=20=E2=80=94=20SCAL-295712=20?= =?UTF-8?q?et=20al?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GITHUB FILE WRITE PROTOCOL: main size=32691, working branch had 21537 (truncated). This commit restores all prior release entries from main and prepends the correct 26.8.0.cl new content block. No prior content is removed. --- modules/ROOT/pages/whats-new.adoc | 524 ++++++++++++++++++++++++++++-- 1 file changed, 500 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index e997d3ecf..8a0f1e19f 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -26,8 +26,7 @@ This page lists new features, enhancements, and deprecated functionality introdu // ============================================================ // SOURCE: SCAL-295712, SCAL-309481, SCAL-273333, SCAL-312731, SCAL-292918, // SCAL-310399, SCAL-312622, SCAL-309017, SCAL-307283, SCAL-317357, -// SCAL-306340, SCAL-313088, SCAL-273513, SCAL-298371, SCAL-293483, -// SCAL-244749, SCAL-323283, SCAL-303476 +// SCAL-306340, SCAL-313088, SCAL-293483, SCAL-244749, SCAL-323283 // TODO: [WRITER] Confirm the exact calendar month label ("August 2026") with // the release team before publishing. SCAL-295712 targets 26.8.0.cl but // the calendar ship date is not confirmed at time of authoring (2026-07-10). @@ -64,6 +63,7 @@ Starter prompts (in `SpotterChatViewConfig`)::: * `enableStarterPrompts` — When set to `true`, shows onboarding starter prompts on initial load. Default: `false`. Action IDs for `hideActions` or `disableActions`::: +// TODO: [WRITER] Verify these Action enum values against the released SDK 1.51.0 types.ts before publishing. * `Action.ShowAnalysts`, `Action.CreateAnalyst`, `Action.EditAnalyst`, `Action.MakeCopyAnalyst`, `Action.ShareAnalyst`, `Action.DeleteAnalyst` For more information, see xref:embed-spotter.adoc#spotter-analysts[Spotter Analysts in embedded applications]. @@ -91,7 +91,7 @@ For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Live ==== Spotter onboarding starter prompts [.version-badge.new]#New# // SOURCE: SCAL-293483, SCAL-314448 // SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl -// TODO: [WRITER] Verify that customStarterPrompts is supported in SpotterEmbed (in addition to LiveboardEmbed and AppEmbed) by checking the SDK source for SpotterEmbedViewConfig. +// TODO: [WRITER] Verify that enableStarterPrompts is supported in SpotterEmbed (in addition to LiveboardEmbed and AppEmbed) by checking the SDK source for SpotterEmbedViewConfig. Embedded Spotter now supports onboarding starter prompts to guide first-time users. When enabled, Spotter presents suggested questions based on the connected data model. Use `enableStarterPrompts: true` in `SpotterChatViewConfig` to enable this feature. For more information, see xref:embed-spotter.adoc#_enable_starter_prompts[Enable starter prompts in Spotter]. @@ -102,7 +102,7 @@ For more information, see xref:embed-spotter.adoc#_enable_starter_prompts[Enable ==== Navigation and homepage V1/V2 deprecated [.version-badge.deprecated]#Deprecated# // SOURCE: SCAL-312731 // TODO: [WRITER] Confirm exact release in which V1 and V2 will be fully REMOVED (not just deprecated) with the product team. Update the phrase "a future release" with the specific version once confirmed. -// TODO: [WRITER] Verify with SDK team whether existing embeds that omit discoveryExperience automatically fall back to V3, or require explicit SDK configuration. +// TODO: [WRITER] Verify with SDK team whether existing embeds that omit discoveryExperience automatically fall back to V3, or require explicit SDK configuration update. Starting from ThoughtSpot Cloud 26.8.0.cl, the classic V1 and V2 navigation and homepage experience modes are deprecated. All ThoughtSpot Embedded sessions now render in the V3 navigation experience by default. ThoughtSpot recommends updating your embed configuration to set `discoveryExperience` explicitly with `PrimaryNavbarVersion.Sliding` and `HomePage.ModularWithStylingChanges` to ensure compatibility with future releases. @@ -112,9 +112,9 @@ For migration guidance, see xref:full-app-customize.adoc#nav-v1-v2-deprecation[V --- [discrete] -==== TSE: Multiple features now generally available +==== TSE: Multiple features now generally available [.version-badge.new]#New# // SOURCE: SCAL-295712 -// TODO: [WRITER] Confirm with product team the exact set of features going GA in 26.8.0.cl. The list below is based on SCAL-295712 description. Verify: Hide Irrelevant Filters, Compact Header, Cover Filter Page, Aether UI are all included. +// TODO: [WRITER] Confirm with product team the exact set of features going GA in 26.8.0.cl. Verify that Hide Irrelevant Filters, Compact Header, Cover Filter Page, and Aether UI are all included in 26.8.0.cl GA. The following features, previously in Early Access, are now generally available for ThoughtSpot Embedded instances: * *Hide Irrelevant Filters* — Filters that are not relevant to the displayed visualization are automatically hidden. @@ -129,9 +129,9 @@ No SDK configuration changes are required. These features are enabled by default [discrete] ==== WYSIWYG Liveboard PDF export [.version-badge.new]#New# // SOURCE: SCAL-309481 -// TODO: [WRITER] Verify whether `isContinuousLiveboardPDFEnabled` (introduced in SDK 1.48.0 beta) is the same feature going GA in 26.8.0.cl, or a separate capability. Confirm with the Liveboard team. -// TODO: [WRITER] Verify backward compatibility: confirm whether existing `DownloadLiveboardAsContinuousPDF` action behavior is unchanged for embeds using SDK 1.48.x+. -The WYSIWYG Liveboard PDF export experience is now generally available for ThoughtSpot Embedded instances. When this feature is enabled, the exported PDF matches the exact Liveboard layout as displayed on screen, rendering visualizations in a continuous layout rather than splitting them across A4 pages. +// TODO: [WRITER] Verify whether `isContinuousLiveboardPDFEnabled` (introduced in SDK 1.48.0 as Beta) is the same capability going GA in 26.8.0.cl, or a separate WYSIWYG capability. Confirm with the Liveboard team. +// TODO: [WRITER] Verify backward compatibility: confirm that existing `DownloadLiveboardAsContinuousPDF` action behavior is unchanged for embeds using SDK 1.48.x+. +The WYSIWYG Liveboard PDF export experience is now generally available for ThoughtSpot Embedded instances. When enabled, the exported PDF matches the exact Liveboard layout as displayed on screen, rendering visualizations in a continuous layout rather than splitting them across A4 pages. --- @@ -152,8 +152,8 @@ These privileges can be assigned independently per user or group. Update privile [discrete] ==== Personalized Views portability [.version-badge.new]#New# // SOURCE: SCAL-307283 -// TODO: [WRITER] Confirm exact TML field names `owned_by` and `obj_id` in the Personalized View TML schema with the TML/deployment team (Rajesh / Platform team) before publishing. -// TODO: [WRITER] Confirm the import merge behavior — does a duplicate check on `obj_id` prevent duplicate creation, or does it update the existing view? +// TODO: [WRITER] Confirm exact TML field names `owned_by` and `obj_id` in the Personalized View TML schema with the TML/deployment team before publishing. +// TODO: [WRITER] Confirm the import merge behavior — does a duplicate check on `obj_id` update the existing view, or skip the import? ThoughtSpot improves the portability of Personalized Views across environments: * A new `owned_by` field in the Personalized View TML allows specifying the owner during import. @@ -189,7 +189,7 @@ Embedding applications that relied on discoverability for content visibility sho [discrete] ==== Schedule every-N-minutes option deprecated [.version-badge.deprecated]#Deprecated# // SOURCE: SCAL-244749 -// TODO: [WRITER] Confirm which release the every-N-minutes frequency option will be fully removed with the Schedules team. Also confirm whether existing schedules are automatically migrated to the next supported frequency. +// TODO: [WRITER] Confirm which release the every-N-minutes frequency option will be fully removed. Confirm whether existing schedules are automatically migrated to the next supported frequency. The *every N minutes* frequency option for Liveboard scheduled jobs is deprecated in 26.8.0.cl. New scheduled jobs cannot be created with this frequency. Existing jobs configured with this frequency continue to run until they are edited or the option is removed in a future release. Embedding applications that create scheduled jobs programmatically via the REST API should remove any usage of the `every_n_minutes` frequency in schedule creation requests. @@ -199,7 +199,7 @@ Embedding applications that create scheduled jobs programmatically via the REST [discrete] ==== Business Terms autogeneration deprecated [.version-badge.deprecated]#Deprecated# // SOURCE: SCAL-313088 -// TODO: [WRITER] Confirm whether existing auto-generated business terms are preserved or removed after this deprecation. Confirm which Spotter coaching REST API endpoints are affected (SCAL-313088 does not include an API spec). +// TODO: [WRITER] Confirm whether existing auto-generated business terms are preserved or removed after this deprecation. Confirm which Spotter coaching REST API endpoints are affected. The automatic generation of Business Terms for Spotter model coaching is deprecated. The Business Terms fields in the Spotter coaching interface are now available exclusively for adding custom context. Administrators who manage Spotter model coaching should review existing business term configurations. --- @@ -207,7 +207,7 @@ The automatic generation of Business Terms for Spotter model coaching is depreca [discrete] ==== Spotter Model [.version-badge.new]#New# // SOURCE: SCAL-306340 -// TODO: [WRITER] Confirm whether Spotter Model GA milestone is 26.8.0.cl or jun.26.mt (the Jira fix version field is ambiguous). Verify with the AI Modeling team before publishing. +// TODO: [WRITER] Confirm whether Spotter Model GA milestone is 26.8.0.cl or jun.26.mt. Verify with the AI Modeling team before publishing. // TODO: [WRITER] Add xref to the Spotter Model page in developer-docs once the page filename is confirmed. Spotter Model — which allows administrators to configure, train, and manage a dedicated AI model for Spotter — is now generally available. For more information, see the Spotter Model documentation. @@ -298,7 +298,7 @@ For more information, see xref:developer-playground.adoc#spottercode-panel[Using [discrete] ==== Org isolation for per-org SAML and OIDC authentication -ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. +ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. For more information, see xref:orgs.adoc#per-org-sso-isolation[SSO and Org isolation]. --- @@ -352,17 +352,25 @@ This release introduces the following enhancements for Spotter AI workflows and * Spotter embedding: + Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. +* Spotter AI APIs: + +//** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. + New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. -* Spotter embedding in AppEmbed: + -The `AppEmbed` component now supports Spotter sidebar configuration through the `spotterSidebar` object. For more information, see xref:embed-spotter.adoc[Embed Spotter experience]. +--- -* Action IDs for Spotter chat UI elements: + -The SDK introduces new action IDs to control the visibility of specific UI components in the chat panel: -** `Action.SpotterChatConnectorResources` — For the connector resources section. -** `Action.SpotterChatConnectors` — For the connectors panel. -** `Action.SpotterChatModeSwitcher` — For the mode switcher. +[discrete] +==== Developer page enhancements +The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: -For more information, see xref:embed-spotter.adoc[Embed Spotter experience]. +* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. +* Removal of REST API v1 + +The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. +* Removal of GraphQL playgrounds + +The menu link to the GraphQL playground has been removed from the UI. + +[discrete] +==== Liveboard browser cache refresh +To improve load performance and reduce, you can now enable the Liveboard cache option with a **Refresh** button to allow your users to clear cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Liveboard browser cache refresh]. --- @@ -374,8 +382,476 @@ The Visual Embed SDK version 1.49.0 includes several new features and enhancemen [discrete] ==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +|===== + + +== May 2026 + +**Release version**: ThoughtSpot Cloud 26.5.0.cl + +*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + +*Recommended SDK versions*: Visual Embed SDK v1.48.0 and later + + +[.cl-table, cols="2,4", frame=none, grid=none] +|===== +a| +[.cl-label] +*Version 26.5.0.cl* + +a| + + +[discrete] +==== Liveboard downloads + +Continuous Liveboard PDF export [beta betaBackground]^Beta^:: +In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. + +Liveboard download in XLSX and CSV formats:: +Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. + +Excel exports for pivot tables:: +Pivot table visualizations can now be exported to Excel format. + +For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard download options]. + +--- + +[discrete] +==== Visualization edit interface within the Liveboard view + +Users can now edit the underlying query of an answer directly within the Liveboard. When this feature is enabled, the edit button for visualization appears in the answer's floating toolbar when the Liveboard is opened in the edit mode. Clicking the edit button opens the Answer interface preloaded with the answer's current query context. You can make the edits and save the changes without leaving the Liveboard. + +--- + +[discrete] +==== KPI charts in embedded Liveboards + +Embedded Liveboards support advanced controls KPI chart customization. For more information, see link:https://docs.thoughtspot.com/cloud/latest/chart-kpi#advanced[KPI charts]. + +--- + +[discrete] +==== Per-org and per-user timezone control via variables [beta betaBackground]^Beta^ + +You can centrally control timezone behavior per org and per user in embedded deployments using the new template variable `ts_user_timezone` and Variable APIs. + +For multi-org and multi-tenant environments, each tenant org and user can be configured independently, guaranteeing isolation and consistency of time-based analytics across regions. Administrators can reference the timezone variable in formulas to render and filter timestamp data correctly for each embedded user, without separate content per region. + +--- + +[discrete] +==== Timezone-aware keyword filtering [beta betaBackground]^Beta^ +ThoughtSpot now supports resolving relative date and time keywords, such as `today`, `yesterday`, and `last 7 days`, using a configurable per-user or per-Org timezone, instead of the system default timezone on a ThoughtSpot instance. This feature eliminates timezone-based inconsistencies in multi-region embedded deployments and removes the need for custom workarounds. + +For more information, see xref:timezone.adoc[Timezone-aware keywords and filters]. + +[NOTE] +==== +The timezone awareness feature is in Beta and disabled by default. To enable this feature, contact ThoughtSpot Support. +==== + --- +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.48.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +This release introduces new Spotter API endpoints and modifications to the agent conversation APIs, and deprecates legacy agent endpoints. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + |===== + + +== April 2026 + +**Release version**: ThoughtSpot Cloud 26.4.0.cl + +*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Recommended SDK versions*: Visual Embed SDK v1.47.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== + +a| +[.cl-label] +*Version 26.4.0.cl* + +a| + +[discrete] +==== Theme builder in AI mode + +The Theme Builder now has an AI mode that enables developers to explore and preview style customizations for their embedded application's branding using natural language instructions and uploaded brand assets. You can execute style updates such as applying colors directly from a PDF branding guide, updating all button shapes with higher contrast, matching a header to a dark background based on a screenshot, or importing typography and spacing from a JSON file. In the AI mode, Theme builder interprets your intent and applies the changes instantly. + +For more information, see xref:theme-builder.adoc[Theme builder]. + +--- + + +[discrete] +==== Webhook integration +In this release version, the following enhancements are introduced in the webhook configuration and delivery status monitoring workflows: + +Channel validation:: +Administrators can verify the connection status of a webhook channel by sending a test payload in a `POST` request to the `/api/rest/2.0/system/communication-channels/validate` REST API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[Webhook channel validation]. + +Monitor webhook delivery:: +Administrators can also monitor the status of a webhook delivery via a `POST /api/rest/2.0/jobs/history/communication-channels/search` API request. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. + +Support for custom HTTP headers in webhook requests:: +When configuring or updating a webhook, you can now specify custom headers to include in every outbound request, in addition to the standard HTTP and authentication headers that ThoughtSpot sends. For more information, refer to the xref:webhooks-lb-schedule.adoc#_create_a_webhook[webhook documentation]. + +--- + + +[discrete] +==== Spotter embed enhancements +You can now customize the appearance and contents of the chat history sidebar panel in Spotter embedding. + +You can also customize the branding and logo in the Spotter chat interface. + +For more information, see xref:embed-spotter.adoc#_chat_history_panel[Customizing chat history sidebar] and xref:embed-spotter.adoc#_hiding_the_spotter_icon_and_thoughtspot_branding_chat_interface[Hiding logo and brand label in Spotter chat interface]. + +--- + +[discrete] +==== Liveboard enhancements +The following enhancements are introduced in Liveboard export and filtering workflows. + +Embedding a personalized Liveboard view:: +You can now embed a saved personalized Liveboard view using the `personalizedViewId` and load it along with the `liveboardId` in your app. + +Centralized filter modal:: +Liveboard users can modify multiple filters and parameters in a single session using the centralized filter modal. This is an early access feature and disabled by default on ThoughtSpot embedded instances. To enable this feature on embedded Liveboards, set the `isCentralizedLiveboardFilterUXEnabled` to `true`. + +Current period inclusion in rolling date filters:: +The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. + +Liveboard PNG export:: +The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API documentation]. + +--- + + +[discrete] +==== Full app embedding +In full application embedded deployments with the V3 navigation and home page experience, the default list page experience is set to ListPage v3 experience. + +The ListPage V3 experience provides a refreshed list layout and styling, including the following enhancements: + +* The **Views** column to show the number of views for each object. +* Sorting options for **Name**, **Author**, and **Views** columns. +* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. + +For more information, see xref:full-app-customize.adoc#_customize_list_page_experience[List page customization]. + +--- + + +[discrete] +==== Variable API +The variable REST API provides new API endpoints for the following bulk operations: + +* Bulk deletion: +You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. +* Batch update of variable values: +You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. + +[NOTE] +==== +The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. +==== + +For more information, see xref:variables.adoc[Variables documentation]. + +--- + + +[discrete] +==== Metadata parameterization +You can now parameterize multiple properties of metadata objects using `POST /api/rest/2.0/metadata/parameterize-fields`. The legacy endpoint `/api/rest/2.0/metadata/parameterize` is deprecated in 26.4.0.cl and later versions, and is replaced with the new endpoint to allow updating multiple fields in a single API request. + +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization documentation]. + +--- + + +[discrete] +==== Collections [beta betaBackground]^Beta^ +ThoughtSpot embedded users can now use REST APIs v2 to organize different ThoughtSpot objects into organizational containers called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. + +For more information, see xref:collections.adoc[Collections]. + +[NOTE] +==== +These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== +--- + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. + + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- +|=== + +== March 2026 + +**Release version**: ThoughtSpot Cloud 26.3.0.cl + +*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Recommended SDK versions*: Visual Embed SDK v1.46.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== + +a| +[.cl-label] +*Version 26.3.0.cl* + +a| +[discrete] +==== Amazon S3 storage destination for webhook delivery +You can now configure ThoughtSpot to deliver webhook payloads and attachments directly into your own Amazon S3 storage using secure AWS cross-account access. To enable this integration, your AWS administrator must create an IAM role with S3 permissions and trust policy, and then register a webhook in ThoughtSpot to deliver the payloads and attachments directly to your S3 bucket. + +For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. + +--- + +[discrete] +==== Host event enhancements for context-aware routing + +HostEvents in the Visual Embed SDK are enhanced to improve event routing and context targeting in ThoughtSpot embedded applications. + +Developers can use the page context framework in the SDK to route host events to a specific UI layer and align user experience with the product UI behavior in multi-modal contexts. + +For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. + +--- + +[discrete] +==== JWT-based ABAC implementation +The legacy JWT-based approach that uses `filter_rules` and `parameter_values` to implement Attribute-Based Access Control (ABAC) is deprecated. + +As part of this deprecation, the following changes have been introduced to the custom authentication token API workflow and REST API Playground: + +* The `filter_rules` parameter on the custom token authentication page in the REST API Playground is no longer available for new configurations. This change does not affect your existing implementation. + +* The `parameter_values` property is not deprecated in version 26.3.0.cl and remains supported until further notice. However, using parameter values for row-level security use cases will ultimately be deprecated in an upcoming release. + +Existing ABAC implementations that use `filter_rules` will continue to function until further notice. However, we strongly recommend migrating your legacy ABAC implementation to the ABAC via RLS method that uses custom variables. For migration steps, refer to the xref:abac-migration-guide.adoc[ABAC migration guide]. + +For new deployments, use ABAC via RLS with custom variables and pass data security attributes through the `variable_values` property in the custom access token, and define your RLS rules based on those variables. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS]. + +--- + +[discrete] +==== Spotter coaching access across published Orgs +Starting with the 26.3.0.cl release, ThoughtSpot supports publishing Spotter coaching information to other Orgs. Coaching changes from the primary Org are synchronized with the data models published in secondary Orgs. + +Administrators and users with edit access to data models can programmatically control user access to Spotter coaching information using the object privilege REST API endpoint, `/api/rest/2.0/security/metadata/manage-object-privilege`. They can assign `SPOTTER_COACHING_PRIVILEGE` to other users and user groups, allowing access to the coaching information without requiring data model editing or administration privileges. + +Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. + +For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. + +--- + +[discrete] +==== Full application embedding +The height and aspect ratio of the logo in the top-left corner of the ThoughtSpot application interface have been updated for visual alignment and consistency across pages. This enhancement is available only in the V3 navigation and home page experience. + +If you have embedded the full application with the V3 navigation experience, you may notice that the logo appears smaller in the top navigation. This is a design update and does not require any configuration changes to your current embedding implementation. However, we recommend that you review the logo size and appearance, and adjust your custom logo if necessary. + +For information about adding a custom logo image, see xref:customize-style.adoc#logo-change[Customize application logo and favicon]. + +--- + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|=== + +== February 2026 +**Release version**: ThoughtSpot Cloud 26.2.0.cl + +*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Recommended SDK versions*: Visual Embed SDK v1.45.0 and later + + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.2.0.cl* + +a| +[discrete] +==== 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]. + +--- + +[discrete] +==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# +You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an 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]. + +--- + +[discrete] +==== 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]. + +--- + +[discrete] +==== Security settings via REST APIs +Security settings that ensure data security and a seamless embedded user experience can now be configured 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]. + +--- + +[discrete] +==== WebSocket support for external tools +ThoughtSpot supports secure WebSocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. + +To allow a WebSocket host, add the corresponding `wss://` URL to both your CSP allowlists. Only hosts explicitly listed with the `wss://` protocol are permitted. Existing `https://` entries in the allowlists remain unchanged and continue to function as expected. + +For more information, see xref:3rd-party-script.adoc#_allow_websocket_endpoints[External tools and script integration]. + +--- + + +[discrete] +==== 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]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- +|=== + + +== January 2026 + +**Release version**: ThoughtSpot Cloud 10.15.0.cl + +*Upgrade notes*: No breaking changes. + +*Recommended SDK versions*: Visual Embed SDK v1.44.0 and later + + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 10.15.0.cl* + +a| +[discrete] +==== Theme Builder +Theme Builder is now generally available (GA) and will be rolled out to all ThoughtSpot instances in customer deployments over the next few weeks. + +When this feature is enabled on your instance, you can access it from the *Develop* page in ThoughtSpot and use it to customize styles and UX themes directly within the product. + +For more information, see xref:theme-builder.adoc[Theme Builder]. + +--- + +[discrete] +==== V3 navigation and home page experience + +The new V3 navigation and home page experience is now generally available (GA) and can be enabled on ThoughtSpot embedded instances. + +The default UI experience in full application embedding remains the classic (V1) experience until further notice. Developers embedding the full ThoughtSpot application can enable the V3 experience in their applications by setting the appropriate configuration options in their embed code. + +For more information, see xref:full-app-customize.adoc[Customizing full application embedding]. + +--- + +[discrete] +==== Formula variables in RLS rules + +You can now create formula variables using the Variable REST API and use these variables in RLS rules for a specific data context and in ABAC token requests to dynamically assign security attributes to users. + +For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. + +--- + +[discrete] +==== Spotter APIs + +ThoughtSpot introduces new REST APIs for the following Spotter workflows: + +* To send queries to a conversation session with the Spotter agent +* To set natural language (NL) instructions on a model to coach the Spotter system +* To fetch NL instructions configured on a model + +For more information, see xref:spotter-apis.adoc[Spotter APIs]. + +--- + +[discrete] +==== Embed events and parameters to intercept API calls +You can now intercept API calls from the embedded ThoughtSpot application using the `interceptUrls` attribute in the Visual Embed SDK. This feature lets you control API requests in your embedding application and use embed events to modify, block, or handle requests before they are sent to the backend. For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. + +--- + +[discrete] +==== Icon customization enhancements + +You can now replace or customize the chart switcher toggle and icons in the Charts drawer on an Answer or visualization page using SVG sprites. Previously, these icons were fixed to ThoughtSpot defaults and were not configurable. In the new version, these icons are available as SVG components and can be replaced by developers through the xref:customize-icons.adoc[icon customization framework] as needed. + +--- + +[discrete] +==== Mobile Embed SDK +The SDKs for embedding ThoughtSpot components in mobile apps are now Generally Available (GA). For more information about the SDKs and how to embed a ThoughtSpot component in a mobile app, see xref:mobile-embed.adoc[Mobile embed documentation]. + +--- + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API +For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +|=== From 69d6cab26a960994b17efbb355ecb6277cd6ebf0 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 07:56:25 +0530 Subject: [PATCH 13/63] =?UTF-8?q?fix(api-changelog):=20restore=20full=20SD?= =?UTF-8?q?K=20changelog=20+=20prepend=201.51.x=20block=20=E2=80=94=20SCAL?= =?UTF-8?q?-310399,=20SCAL-312622,=20SCAL-309017?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GITHUB FILE WRITE PROTOCOL: main size=89925 bytes. Prior commit had truncated to 14575 bytes (loss of 75,350 bytes). This commit restores all prior SDK changelog entries from main and prepends the correct 1.51.x new content block. No prior content is removed. --- modules/ROOT/pages/api-changelog.adoc | 726 +++++++++++++++++++++++++- 1 file changed, 722 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 3247a3758..8f8e6aab0 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -10,8 +10,7 @@ This page documents the changes introduced in each release of the Visual Embed S // ============================================================ // SOURCE: src/embed/conversation.ts, src/embed/spotter-viz-utils.ts, -// src/embed/app.ts, src/embed/liveboard.ts -// (visual-embed-sdk main branch, verified 2026-07-10) +// src/types.ts (visual-embed-sdk main branch, verified 2026-07-10) // SOURCE: SCAL-310399, SCAL-312622, SCAL-293483, SCAL-309017 // TODO: [WRITER] Confirm calendar month label — "August 2026" if release ships in // late July / early August 2026. Verify with release team. @@ -58,7 +57,7 @@ Default: `false` + New action IDs for `disableActions` and `hideActions` (Analyst actions): // TODO: [WRITER] Verify these Action enum values exist in the SDK 1.51.0 release of types.ts. -// Source: SCAL-312622 Jira description (not yet confirmed in types.ts grep). +// Source: SCAL-312622 Jira description. Not yet confirmed in types.ts grep at authoring time. [width="100%", cols="2,4"] |==== |Action ID |Description @@ -334,6 +333,725 @@ EmbedEvent:: * `EmbedEvent.Subscribed` + The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. * `EmbedEvent.Error` + -The `EmbedEvent.Error` event now includes an error code in the payload for more specific error identification. +The `EmbedEve +nt.Error` now fires on HostEvent payload validation failures. +* `EmbedEvent.ChangePersonalizedView` + +Emits when a user selects a different Personalized View or resets to default. +HostEvent:: +* `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + +The response payload of the `GetExportRequestForCurrentPinboard` passthrough +host event has been updated to include a `type` discriminator field, making it +consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. + +* `HostEvent.SelectPersonalizedView` + +Triggers the selection of a specific Personalized View and resets the default view on a Liveboard. + + +⚠️Deprecated events and action IDs️:: +The following events are deprecated and replaced with new event IDs. + +* `EmbedEvent.UpdatePersonalisedView`. Use `EmbedEvent.UpdatePersonalizedView`. +* `EmbedEvent.SavePersonalisedView`. Use `EmbedEvent.SavePersonalizedView`. +* `EmbedEvent.DeletePersonalisedView`. Use `EmbedEvent.DeletePersonalizedView`. +* `HostEvent.ResetLiveboardPersonalisedView`. Use `HostEvent.ResetLiveboardPersonalizedView`. +* `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. +* `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. + + +|==== + + +== Version 1.47.x, April 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** + +The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: + +* `enablePastConversationsSidebar` + +Controls the visibility of the past conversations sidebar panel. The chat history panel is disabled by default in embed view. When this property in `spotterSidebarConfig` is specified, it takes precedence over the standalone `enablePastConversationsSidebar` setting, which is deprecated from v1.47.0. + +* `spotterSidebarTitle` + +Allows adding custom title text for the sidebar header. + +* `spotterSidebarDefaultExpanded` + +Sets the default state of the sidebar to expanded or collapsed view. + +* `spotterChatRenameLabel` + +Allows setting a custom label for the **Rename** action in the conversation edit menu. + +* `spotterChatDeleteLabel` + +Allows setting a custom label for the **Delete** action in the conversation edit menu. + +* `spotterDeleteConversationModalTitle` + +Allows editing the title text of the chat delete confirmation modal. + +* `spotterPastConversationAlertMessage` + +Sets a custom message text for the past conversation banner alert. Defaults to the translated alert message. + +* `spotterBestPracticesLabel` + +Allows customizing the label for the best practices button in the sidebar footer. + +* `spotterDocumentationUrl` + +The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. + +* `spotterConversationsBatchSize` + +Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. + +* `spotterNewChatButtonTitle` + +Allows customizing the title text for the **New chat** button in the sidebar. + +|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** + +The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. + +Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. + +[source,javascript] +---- +// Deprecated +enablePastConversationsSidebar: false, + +// Recommended +spotterSidebarConfig: { + enablePastConversationsSidebar: true, + //... other config properties +} +---- + +|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** + +The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. + +* `hideToolResponseCardBranding` + +When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. + +* `toolResponseCardBrandingLabel` + +Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. + +[NOTE] +==== +These settings do not affect the external MCP tool branding. +==== + +|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** + +Personalized Liveboard view:: + +The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. + +Centralized Liveboard filter setting:: + +When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. + +|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** + +If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. +To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. +|==== + + +== Version 1.46.x, March 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** + +The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. + +* To enable this feature, set `useHostEventsV2` to `true`. +* To retrieve the current context, use `getCurrentContext()`. +* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. + +For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. + +|[tag redBackground]#DEPRECATED# a| **dataPanelV2** + +The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. + +|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** +The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. + +Chat history sidebar customization:: + +//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. +//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. +* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: +** `Action.DataModelInstructions` for the data model instructions icon. +** `Action.SpotterSidebarHeader` for the chat history sidebar header +** `Action.SpotterSidebarFooter` for the chat history sidebar footer +** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. +** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. +** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. +** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. +** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. +** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. +//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. + +Events:: +* `HostEvent.DataModelInstructions` + +Opens the Data Model instructions modal. +* `EmbedEvent.DataModelInstructions` + +Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. +* `EmbedEvent.SpotterConversationRenamed` + +Is emitted when a user renames a saved chat. +* `EmbedEvent.SpotterConversationDeleted` + +Is emitted when a saved chat is deleted. +* `EmbedEvent.SpotterConversationSelected` + +Is emitted when a saved chat is selected in the chat history sidebar. + +|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + + +Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. + +|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + +* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. +* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. +|==== + +== 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 `auto_mode`. +* 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. + +[NOTE] +==== +On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. +==== + +|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + + +Styling and grouping:: + +* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute 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 *Manage publishing* +* `Action.Unpublish` for *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`, and `NETWORK`. +* `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"] +|==== + +|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + + +The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. +To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. + +|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + +The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: + +//* `enableApiIntercept` + +//When set to true, enables the feature on your ThoughtSpot embed. +* `interceptUrls` + +Allows configuring which API calls to intercept. +* `interceptTimeout` + +Sets the timeout duration for handling interception. +* `isOnBeforeGetVizDataInterceptEnabled` + +When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. +* `EmbedEvent.ApiIntercept` + +Emits when an API call matching the conditions defined in `interceptUrls` is detected. + +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"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* + +The following enumerations are available for code-based custom actions: + +* `CustomActionTarget` + +To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. +* `CustomActionsPosition` + +To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. +|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + +The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. +|==== + +== Version 1.42.0, October 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* + +The Visual Embed SDK now supports runtime overrides in Spotter embed. + +* To apply runtime filters, use the `runtimeFilters` object +* To apply runtime Parameters, use the `runtimeParameters` object. + +|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + +To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. + +The SDK also provides the following action IDs: + +* `Action.PngScreenshotInEmail` + +Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. +* `Action.RemoveAttachment` + +Allows the user to remove an attachment from the email configuration in the schedule email dialog. +|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* + +Action IDs:: +The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: + +* `Action.SpotterWarningsBanner` + +Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. +* `Action.SpotterWarningsOnTokens` + +Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. +* `Action.SpotterTokenQuickEdit` + +Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. +|==== + +== Version 1.41.0, September 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* + +The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. + +For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. + +|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* + +The following event handlers are now available for Spotter embed: + +* `EmbedEvent.SpotterInit` + +Fires when Spotter embed component rendering is initialized. +* `EmbedEvent.QueryChanged` + +Fires when the Spotter query is updated by the user. +* `HostEvent.AskSpotter` + +Triggers *Ask Spotter* action for visualizations. +* `HostEvent.GetParameters` + +Triggers the action to fetch runtime Parameters applied on a visualization. +* `HostEvent.UpdateParameters` + +Triggers the action to update runtime Parameters for a Spotter-generated Answer. +* `HostEvent.GetTML` + +Triggers the action to get TML representation of a Spotter-generated Answer. + +For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* + +You can now use the following host events in Spotter Agent embedding: + +- `HostEvent.DownloadAsCsv` + +Triggers the action to download a Spotter-generated Answer in CSV format. +- `HostEvent.DownloadAsPng` + +Triggers the action to download a Spotter-generated Answer in PNG format. +- `HostEvent.DownloadAsXlsx` + +Triggers the action to download a Spotter-generated Answer in XLSX format. +- `HostEvent.DownloadAsPdf` + +Triggers the action to download the PDF version of a Spotter-generated Answer. +- `HostEvent.Pin` + +Triggers the action to add a Spotter-generated Answer to a Liveboard. +- `HostEvent.Save` + +Triggers the *Save* action for a Spotter-generated Answer. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* + +You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +You can also set the margin property for lazy loading to define when the visualization should load. + +For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. + +|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + + +You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. + +When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. +|==== + +== Version 1.40.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + +Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. +|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + +Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. + +|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + + +If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. + +For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. + +|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + + +The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. + +|[tag greenBackground]#NEW FEATURE# a| *Host events* + + +In this version, the SDK introduces the following host event handlers: + +- `HostEvent.ExitPresentMode` + +Triggers the exit action that allows users to exit the Liveboard or visualization present mode. +- `HostEvent.SpotterSearch` + +Triggers a search operation for the specified query string in Spotter embed. +- `HostEvent.PreviewSpotterData` + +Triggers the *Preview data* action that shows the data used for Spotter conversations. +- `HostEvent.ResetSpotterConversation` + +Triggers the *Reset* action to reset a Spotter conversation. +- `HostEvent.EditLastPrompt` + +Triggers the edit prompt action. +- `HostEvent.DeleteLastPrompt` + +Triggers the delete prompt action. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* + +You can now use the following host events in Spotter embed: + +- `HostEvent.DownloadAsCsv` +- `HostEvent.DownloadAsPng` +- `HostEvent.DownloadAsXlsx` +- `HostEvent.Edit` +//- `HostEvent.GetParameters` +//- `HostEvent.GetTML` +- `HostEvent.MakeACopy` +- `HostEvent.Pin` +- `HostEvent.Save` + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* + +The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. +This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +[NOTE] +==== +To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. +==== +|==== + + +== Version 1.39.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + +The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: + +* `ConversationEmbed` + +Replaced with `SpotterEmbed` +* `ConversationViewConfig` + +Replaced with `SpotterEmbedViewConfig` +* `BodylessConversation` + +Replaced with `SpotterAgentEmbed` +* `BodylessConversationViewConfig` + +Replaced with `SpotterAgentEmbedViewConfig` + +The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. + +|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + +For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. + +[NOTE] +The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. + +|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* + +New embed events:: + +- `EmbedEvent.ExitPresentMode` + +Emits when a user exits the Liveboard or visualization presentation mode. +- `EmbedEvent.LastPromptDeleted` + +Emits when a query prompt in Spotter embed is deleted. +- `EmbedEvent.LastPromptEdited` + +Emits when a query prompt in Spotter embed is edited. +- `EmbedEvent.ResetSpotterConversation` + +Emits when a Spotter query is reset. +- `EmbedEvent.PreviewSpotterData` + +Emits when a user clicks the Preview data button in the Spotter conversation panel. +- `EmbedEvent.SpotterQueryTriggered` +Emits when a Spotter query is triggered. + +The following embed events are also supported in Spotter embed: + +- `EmbedEvent.AddRemoveColumns` +- `EmbedEvent.AnswerChartSwitcher` +- `EmbedEvent.AuthExpire` +- `EmbedEvent.AuthInit` +- `EmbedEvent.CopyToClipboard` +- `EmbedEvent.CustomAction` +- `EmbedEvent.Data` +- `EmbedEvent.DataSourceSelected` +- `EmbedEvent.DialogClose` +- `EmbedEvent.DialogOpen` +- `EmbedEvent.Download` +- `EmbedEvent.DownloadAsCsv` +- `EmbedEvent.DownloadAsPng` +- `EmbedEvent.DownloadAsXlsx` +- `EmbedEvent.DrillDown` +- `EmbedEvent.DrillExclude` +- `EmbedEvent.DrillInclude` +- `EmbedEvent.Edit` +- `EmbedEvent.Error` +- `EmbedEvent.Load` +- `EmbedEvent.Pin` +- `EmbedEvent.Save` +- `EmbedEvent.TableVizRendered` +- `EmbedEvent.VizPointClick` +- `EmbedEvent.VizPointDoubleClick` +- `EmbedEvent.VizPointRightClick` + +For more information, see xref:EmbedEvent.adoc[EmbedEvent]. + +|==== + +== Version 1.38.0, June 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + +Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. + +To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. + +Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI. + +For more information, see xref:customize-text-strings.adoc[Customize text strings]. + +|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + + +In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: + +* *Author* + +`hiddenListColumns: [ListPageColumns.Author]` +* *Favorite* + +`hiddenListColumns: [ListPageColumns.Favourite]` +* *Last modified* + +`hiddenListColumns: [ListPageColumns.DateSort]` +* *Tags* + +`hiddenListColumns: [ListPageColumns.Tags]` +* *Share* + +`hiddenListColumns: [ListPageColumns.Share]` + + +For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. +|==== + +== Version 1.37.0, April 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. +This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. + +For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. + +|[tag greenBackground]#NEW FEATURE# a| +You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. + +|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: + +Embed Events:: + +* `EmbedEvent.TableVizRendered` + +Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. + +* `EmbedEvent.CreateLiveboard` + +Emits when a Liveboard is created. + +Host Events:: + +* `HostEvent.TransformTableVizData` + +Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. + +* `HostEvent.Remove` + +Triggers the *Delete* action on a Liveboard. +|==== + +== Version 1.36.0, February 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The following HostEvents now allow custom parameters to set object properties programmatically: + +* `HostEvent.SaveAnswer` + +Allows adding `name` and `description` text strings. When these parameters are defined, the event triggers the Save action to save the Answer with the predefined properties without opening the *Describe your Answer* modal. +* `HostEvent.Pin` + +Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. + +For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. + +|[tag greenBackground]#NEW FEATURE# a| + +New configuration attributes:: + +* `disableSourceSelection` + +Disables data source selection panel for embed users when set to `true`. +* `hideSourceSelection` + +Hides data source selection panel when set to `true` +* `locale` + +Sets the xref:locale-setting.adoc[locale and regional settings] for the Spotter interface. +* `showSpotterLimitations` + +Shows functional limitations of Spotter when set to `true` +* `hideSampleQuestions` + +Hides sample questions that appear on the default Spotter page. + +Action IDs for menu customization:: +Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions and elements in the embedded Spotter interface: + +* `Action.PreviewDataSpotter` + +The *Preview data* button on the Spotter conversation panel. +* `Action.ResetSpotterChat` + +The *Reset* button on the Spotter conversation panel. +* `Action.SpotterFeedback` + +The feedback widget on Spotter-generated charts. +* `Action.EditPreviousPrompt` + +The edit icon on the prompt panel. +The Prompt panel appears after Spotter generates a response to a user query. +* `Action.DeletePreviousPrompt` + +The delete icon on the prompt panel. + +//// +* `Action.EditTokens` + +The option to edit tokens on a Spotter-generated chart or table. +//// +CSS variables:: + +The following new CSS variables are available for Spotter interface customization: + +* `--ts-var-spotter-input-background` +* `--ts-var-spotter-prompt-background` + +For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. +|[tag greenBackground]#NEW FEATURE# a| + + +Configuration attributes:: + +* `hideIrrelevantChipsInLiveboardTabs` + +Hides filter chips on a Liveboard when set to `true`. + +* `isLiveboardCompactHeaderEnabled` + +Enables the compact Liveboard header feature when set to `true`. + +Action IDs:: +Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: + +* `Action.DisableChipReorder` + +ID for the action that disables filter chip reordering. +* `Action.ChangeFilterVisibilityInTab` + +|==== + +== Version 1.35.0, December 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: + +* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface +* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. + +For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. +|==== + +== Version 1.34.0, November 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: + +* `SpotterEmbed` + +Embeds Spotter conversation interface in your app +* `SpotterAgentEmbed` + +Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. + +For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. + +|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: + +* `showLiveboardVerifiedBadge` + +Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. +* `showLiveboardReverifyBanner` + +Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. +* `Action.KPIAnalysisCTA` + +Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. + +|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. + +|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: + +* `collapseDataPanel` +Minimizes the data panel view. Users can click the data panel header any time to expand the panel. +* `collapseSearchBar` +Sets the initial state of the search bar when embedding a saved Answer. + +|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: + +* `HomeLeftNavItem.LiveboardSchedules` + +The Liveboard schedules menu on the left navigation panel. + +Action enumerations:: + +* `Action.EditScheduleHomepage` + +To show, disable, or hide the *Edit* action on the *Liveboard schedules* page +* `Action.PauseScheduleHomepage` + +To show, disable, or hide the *Pause* action on the *Liveboard schedules* page +* `Action.ViewScheduleRunHomepage` + +To show, disable, or hide the *View run history* action on the *Liveboard schedules* page +* `Action.DeleteScheduleHomepage` + +To show, disable, or hide the *Delete* action on the *Liveboard schedules* page +* `Action.UnsubscribeScheduleHomepage` + +To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page |==== From 7566214cce78e4d91026c02ca0fff8f7e624b05f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 07:58:16 +0530 Subject: [PATCH 14/63] =?UTF-8?q?fix(rest-apiv2-changelog):=20restore=20fu?= =?UTF-8?q?ll=20changelog=20+=20retain=2026.8.0.cl=20block=20=E2=80=94=20S?= =?UTF-8?q?CAL-307283,=20SCAL-317357,=20SCAL-273333,=20SCAL-307522,=20SCAL?= =?UTF-8?q?-244749?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GITHUB FILE WRITE PROTOCOL: main size=65133. Working branch had 13280 bytes (loss of ~51853 bytes). This commit prepends the correct 26.8.0.cl block and restores all prior release entries from main. No prior content is removed. --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 183 +++++++++++++++++++ 1 file changed, 183 insertions(+) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index ceda0f125..db2225000 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,12 +8,14 @@ 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]. +// ============================================================ // SOURCE: SCAL-307283, SCAL-317357, SCAL-273333, SCAL-307522, SCAL-313088, SCAL-244749 // TODO: [WRITER] Confirm the release month label. "August 2026" is inferred from the 26.8.0.cl version pattern. Verify with the release team before publishing. // TODO: [WRITER] SCAL-307522 Spotter ST Memory Migration APIs — no confirmed API spec, endpoint names, or request/response schemas were available at time of authoring. Verify all endpoint paths and parameters with Balakrishna Moravineni / Agent Coaching team before publishing this section. // TODO: [WRITER] SCAL-273333 — Confirm the exact REST API privilege enum string values for "Can Download Visuals" and "Can Download Detailed Data" with the access control / product team before publishing. // TODO: [WRITER] SCAL-317357 — Confirm the exact API endpoint path for updating Collections obj_id. Path `POST /api/rest/2.0/metadata/identity/update` is inferred from the Jira description; verify with the platform team. // TODO: [WRITER] SCAL-244749 — Confirm whether the schedule frequency deprecation affects any REST API schedule endpoints directly (e.g., POST /api/rest/2.0/schedules/create), or only the UI. If the API is affected, add a deprecation callout to the schedules API reference page. +// ============================================================ == Version 26.8.0.cl, August 2026 @@ -213,3 +215,184 @@ Exports from this endpoint inherently reflect any row-level security (RLS) appli Transient content export:: // SOURCE: SCAL-306548 You can now export a transient Answer using the Answer report API. To export a transient Answer, specify the `transient_content` parameter in your API request. + +== Version 26.5.0.cl, May 2026 + +=== Spotter AI APIs + +[IMPORTANT] +==== +This release introduces breaking changes to Spotter agent APIs. The legacy `POST /api/rest/2.0/ai/conversation` endpoint and its related sub-endpoints (`/send-message`, `/create`, and `/delete`) are deprecated in 26.5.0.cl and replaced with new endpoints. + +Existing integrations using the deprecated endpoints will continue to function until the endpoints are removed in a future release. However, ThoughtSpot strongly recommends migrating to the new endpoints as soon as possible. For information about the new endpoints, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. +==== + +New Spotter agent conversation API:: + +ThoughtSpot introduces the following new API endpoints for Spotter agent conversations. These endpoints replace the deprecated legacy conversation endpoints. + +* `POST /api/rest/2.0/ai/agent/conversation/create` + +Creates a new Spotter agent conversation session. To save the conversation, set `enable_save_chat` to `true`. +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/converse` + +Sends a message to an active Spotter conversation session and returns the agent's response. +* `DELETE /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/delete` + +Deletes a Spotter agent conversation session and all its messages. + +For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. + +Deprecated Spotter AI endpoints:: +The following Spotter API endpoints are deprecated: + +* `POST /api/rest/2.0/ai/conversation/create` +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/send-message` +* `DELETE /api/rest/2.0/ai/conversation/{conversation_identifier}/delete` + +== Version 26.4.0.cl, April 2026 + +[#version_26_4_0_cl_april_2026] + +=== Variable API + +The Variable REST API provides new API endpoints for the following bulk operations. + +Bulk deletion:: +You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. + +Batch update of variable values:: +You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. + +[NOTE] +==== +The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. +==== + +For more information, see xref:variables.adoc[Variables]. + +=== Metadata parameterization + +The `/api/rest/2.0/metadata/parameterize` endpoint is deprecated in 26.4.0.cl and later versions. Use the new `/api/rest/2.0/metadata/parameterize-fields` endpoint, which supports parameterizing multiple properties of metadata objects in a single API request. + +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization]. + +=== Liveboard report API + +The Liveboard PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. + +For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API]. + +=== Collections API [beta betaBackground]^Beta^ + +The Collections REST API v2.0 allows creating, managing, and sharing *Collections* programmatically. Collections are organizational containers that allow grouping ThoughtSpot objects such as Liveboards, Answers, data models, tables, and other Collections. + +The following API endpoints are available for managing Collections: + +* `POST /api/rest/2.0/collections/create` + +Creates a new Collection. +* `POST /api/rest/2.0/collections/search` + +Returns a list of all Collections the authenticated user has access to. +* `PUT /api/rest/2.0/collections/{collection_identifier}/update` + +Updates the name, description, or content of an existing Collection. +* `DELETE /api/rest/2.0/collections/{collection_identifier}/delete` + +Deletes a Collection. + +For more information, see xref:collections.adoc[Collections]. + +=== Webhook API enhancements + +* The `/api/rest/2.0/webhooks/create` endpoint includes new parameters for channel validation and custom HTTP headers. +* The `/api/rest/2.0/system/communication-channels/validate` endpoint is introduced for webhook channel validation. +* The `/api/rest/2.0/jobs/history/communication-channels/search` endpoint supports monitoring webhook delivery status. + +For more information, see xref:webhooks-api.adoc[Webhooks API]. + +== Version 26.3.0.cl, March 2026 + +[#_custom_access_token_api] +=== Custom access token API + +The `filter_rules` parameter in the custom access token API is deprecated in 26.3.0.cl. This parameter was used to implement Attribute-Based Access Control (ABAC) via JWT tokens. + +Existing implementations using `filter_rules` will continue to function until further notice. However, ThoughtSpot strongly recommends migrating to the new ABAC via RLS implementation that uses custom variables. For migration steps, see xref:abac-migration-guide.adoc[ABAC migration guide]. + +=== Object privilege API + +The `/api/rest/2.0/security/metadata/manage-object-privilege` API endpoint is enhanced to support assigning `SPOTTER_COACHING_PRIVILEGE` to users and groups. This privilege grants access to Spotter coaching information without requiring data model editing or administration privileges. + +For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. + +=== Webhooks + +Amazon S3 storage for webhook delivery:: +The following parameters are available in the `/api/rest/2.0/webhooks/create` and `/api/rest/2.0/webhooks/{webhook_identifier}/update` endpoints for configuring Amazon S3 storage as a webhook payload delivery destination: + +* `storage_type` — Set to `S3` to use Amazon S3 storage. +* `s3_config` — Contains the S3 bucket name, prefix path, and IAM role ARN for cross-account access. + +For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. + +== Version 26.2.0.cl, February 2026 + +=== Security settings API + +The Security Settings REST API v2.0 allows administrators and developers to configure allowlists for Content Security Policy (CSP), Cross-origin Resource Sharing (CORS), and authentication attributes programmatically. + +The following API endpoints are available: + +* `POST /api/rest/2.0/security/config/search` + +Returns the current security configuration at the cluster or Org level. +* `POST /api/rest/2.0/security/config/update` + +Updates the security configuration settings. + +For more information, see xref:security-settings.adoc[Security settings]. + +=== Trusted authentication API + +The `POST /api/rest/2.0/auth/token/custom` endpoint now supports configuring custom token attributes at the Org level. Administrators can use this endpoint to configure token validity, refresh settings, and other authentication properties. + +=== Rate limits + +ThoughtSpot enforces rate limits on public REST API v2.0 requests. Rate limits are applied globally at the cluster level per client IP and affect all public API endpoints. + +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. + +== Version 10.15.0.cl, January 2026 + +=== Spotter APIs + +ThoughtSpot introduces the following new REST API v2.0 endpoints for Spotter workflows: + +Send a query to Spotter:: +* `POST /api/rest/2.0/ai/conversation/create` + +Creates a new Spotter conversation session. +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/send-message` + +Sends a query to an active Spotter conversation and returns the agent's response. +* `DELETE /api/rest/2.0/ai/conversation/{conversation_identifier}/delete` + +Ends and deletes a Spotter conversation session. + +Configure NL instructions on a model:: +* `PUT /api/rest/2.0/ai/nl-instructions/update` + +Sets natural language (NL) instructions on a data model to coach the Spotter system. +* `GET /api/rest/2.0/ai/nl-instructions` + +Retrieves the NL instructions configured on a data model. + +For more information, see xref:spotter-apis.adoc[Spotter APIs]. + +=== Variable API + +* `POST /api/rest/2.0/template/variables/create` + +Creates a new variable. +* `POST /api/rest/2.0/template/variables/search` + +Returns a list of variables. +* `PUT /api/rest/2.0/template/variables/{identifier}/update` + +Updates a variable. +* `DELETE /api/rest/2.0/template/variables/{identifier}/delete` + +Deletes a variable. _(Deprecated in 26.4.0.cl — use `/api/rest/2.0/template/variables/delete` instead.)_ +* `PUT /api/rest/2.0/template/variables/update-values` + +Assigns values to variables. _(Deprecated in 26.4.0.cl — use `/api/rest/2.0/template/variables/{identifier}/update-values` instead.)_ + +For more information, see xref:variables.adoc[Variables]. + +=== Intercept API calls + +The `interceptUrls` attribute in the Visual Embed SDK allows intercepting API calls from the embedded ThoughtSpot application. Embed events are enhanced to support the `EmbedEvent.ApiIntercept` event, which fires when an API call matching the specified conditions is detected. + +For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. From 7cae28636ec337ae9f3e9460bf48e105befb3dd2 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:14 +0530 Subject: [PATCH 15/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to api-changelog.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] --- modules/ROOT/pages/api-changelog.adoc | 996 +++++++++++++++++++++++++- 1 file changed, 992 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 8f8e6aab0..905178d94 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -187,7 +187,6 @@ Supported embed types: `AppEmbed`. |==== - == Version 1.50.x, July 2026 [width="100%", cols="1,4"] @@ -333,8 +332,7 @@ EmbedEvent:: * `EmbedEvent.Subscribed` + The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. * `EmbedEvent.Error` + -The `EmbedEve -nt.Error` now fires on HostEvent payload validation failures. +The `EmbedEvent.Error` now fires on HostEvent payload validation failures. * `EmbedEvent.ChangePersonalizedView` + Emits when a user selects a different Personalized View or resets to default. @@ -347,7 +345,6 @@ consistent with the shape of other host event responses. It now returns `{ data: * `HostEvent.SelectPersonalizedView` + Triggers the selection of a specific Personalized View and resets the default view on a Liveboard. - ⚠️Deprecated events and action IDs️:: The following events are deprecated and replaced with new event IDs. @@ -1055,3 +1052,994 @@ To show, disable, or hide the *Delete* action on the *Liveboard schedules* page * `Action.UnsubscribeScheduleHomepage` + To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page |==== + +== Version 1.33.x, October 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. + +You can set the `homePageSearchBarMode` property to one of the following options: + +** `aiAnswer` + +Displays the search bar for Natural Language Search. +** `none` +Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. +** `objectSearch` (default) + +Displays Object Search bar on the **Home** page. +|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. +|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: + +Events:: + +* `EmbedEvent.OnBeforeGetVizDataIntercept` + +Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. + +* `EmbedEvent.ParameterChanged` + +Emitted when a Parameter is changed on a saved Answer or Liveboard. + +Actions:: + +* `Action.ManageTags` + +Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. +|==== + +== Version 1.32.x, August 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + + +* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + +* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. +* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. +* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. +* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. +* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. +* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) +For more information, see xref:Action.adoc[Actions]. +|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. +|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. +|| +|==== + +== Version 1.31.x, July 2024 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| Runtime filters + + +* `NOT_IN` operator for Runtime filters. +For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. +* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. +|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. +|==== + +== Version 1.30.0, June 2024 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** + +* `--ts-var-home-watchlist-selected-text-color` + +* `--ts-var-home-card-color` + +* `--ts-var-home-favorite-suggestion-card-text-color` + +* `--ts-var-home-favorite-suggestion-card-background` + +* `--ts-var-home-favorite-suggestion-card-icon-color` + +For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. +|==== + +== Version 1.29.0, May 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** + +With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. + +Action enumeration:: +To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, ++ +[source,JavaScript] +---- +hiddenActions: [Action.AskAi] +---- + +Events:: +* `HostEvent.AskSage` + +Triggers the **Ask Sage** action on a Liveboard visualization. +* `EmbedEvent.AskSageInit` + +Emits when the **Ask Sage** action is initialized. +* `HostEvent.GetParameters` + +Triggers a fetch action to get runtime Parameters. +* `HostEvent.UpdateParameters` + +Updates runtime Parameters +* `HostEvent.ResetLiveboardPersonalisedView` + +Resets a personalized Liveboard view. +* `HostEvent.UpdateCrossFilter` + +Updates cross filters applied on a Liveboard. +|==== + +== Version 1.28.x, April 2024 + +[width="100%" cols="1,4"] +|===== +|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: + +** `Action.VerifiedLiveboard` + +Can be used to show or hide the *Verified Liveboard* banner. +|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: + +* `hiddenhomeleftnavitems` +* `hiddenhomepagemodules` +* `hideapplicationswitcher` +* `hidehomepageleftnav` +* `hideorgswitcher` +* `reorderedhomepagemodules` +* `hiddenhomeleftnavitems` +* `HomeLeftNavItem` + +For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. +|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: + +`EmbedEvent.Rename` + +Emits when an embedded Liveboard or visualization is renamed. +|[tag greenBackground]#NEW FEATURE# a| TML actions + +The following TML menu actions are now grouped under *TML* sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. + +* Export TML +* Edit TML +* Update TML + +To show, hide, or disable these actions in the embedded mode, use the following format: + +[source,JavaScript] +---- + // to show the TML menu and its sub-menu options +visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] +---- + +[source,JavaScript] +---- + // to hide all TML actions +hiddenActions: [Action.TML] +---- + +[source,JavaScript] +---- + // to disable all TML actions +disabledActions: [Action.TML] +---- +|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. +For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. + +|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: + +* `numberFormatLocale` + +* `dateFormatLocale` + +* `currencyFormat` + +For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. + +|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + +The SDK now provides a fetch wrapper that adds the authentication token to the API requests. +For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. +|===== + +== Version 1.27.x, March 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: + +* `Action.AIHighlights` +* `Action.AddToWatchlist` +* `Action.RemoveFromWatchlist` +* `Action.CopyKpiLink` + +For more information, see xref:Action.adoc[Action]. +| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. +|==== + +== Version 1.27.0, January 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. + +For a complete list of methods, functions, interface objects, and properties, see the following pages: + + +* xref:SageEmbed.adoc[SageEmbed] +* xref:SageViewConfig.adoc[SageViewConfig] + +|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. +For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: + +* Host Events +** `HostEvent.UpdateSageQuery` + +Updates the search query string for Natural Language Search operations. +* Embed Events +** `EmbedEvent.CreateConnection` + +Emitted when a user creates a new data connection on the **Data** page. +** `EmbedEvent.CreateWorksheet` + +Emitted when a user creates a new Worksheet. +|==== + +== Version 1.26.0, November 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. +You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. + +|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: + +* `showLiveboardDescription` + +Shows the Liveboard description text when set to `true` +* `showLiveboardTitle` + +Shows the Liveboard title when set to `true` +* `isLiveboardHeaderSticky` + +Sets Liveboard header bar as a fixed element when set to `true` +* `hideLiveboardHeader` + +Hides the Liveboard header when set to `true` +* `hiddenTabs` + +Hides the specified tabs from the Liveboard page +* `visibleTabs` + +Displays the specified tabs on the Liveboard page + +|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: + +Embed events:: +* `EmbedEvent.hiddenTabs` +* `EmbedEvent.visibleTabs` +* `EmbedEvent.UpdatePersonalisedView` +* `EmbedEvent.SavePersonalisedView` +* `EmbedEvent.ResetLiveboard` +* `EmbedEvent.DeletePersonalisedView` +* `EmbedEvent.SageWorksheetUpdated` +* `EmbedEvent.SageEmbedQuery` ++ +For more information, see xref:EmbedEvent.adoc[EmbedEvent]. + +Host events:: + +* `HostEvent.GetTabs` +* `HostEvent.SetVisibleTabs` +* `HostEvent.SetHiddenTabs` +* `HostEvent.GetAnswerSession` +* `HostEvent.UpdateSageQuery` ++ +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: + +* `Action.AddTab` + +Show, disable, or hide the **Add Tab** action on a Liveboard. +* `Action.PersonalisedViewsDropdown` + +Show, disable, or hide the Liveboard views saved by a user. +* `Action.LiveboardUsers` + +Show, disable, or hide Liveboard users. +* `Action.SageAnswerFeedback` +Show, disable, or hide the feedback widget on AI-generated Answer page. +* `Action.EditSageAnswer` +Show, disable, or hide the **Edit** action on the AI-generated Answer page. + +For more information, see xref:Action.adoc[Actions]. +|==== + +== Version 1.25.0, October 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. +For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: + +* `Action.RenameModalTitleDescription` +* `Action.EnableContextualChangeAnalysis` +* `Action.RequestVerification` +* `Action.AddTab` + +For more information, see xref:Action.adoc[Actions]. +|==== + +== Version 1.24.0, September 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. +|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. +|==== + +== Version 1.23.0, August 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + + +* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. +* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. +|==== + +//// +|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + + +* `EmbedEvent.FilterChanged` + +* `HostEvent.GetFilters` + +* `HostEvent.UpdateFilters` +//// + +== Version 1.22.0, June 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. + +For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. + +For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. + +|==== + +//// +|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + + +* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. +* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. +//// + +== Version 1.21.0, May 2023 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: + +* `Action.AxisMenuAggregate` +* `Action.AxisMenuConditionalFormat` +* `Action.AxisMenuEdit` +* `Action.AxisMenuFilter` +* `Action.AxisMenuGroup` +* `Action.AxisMenuNumberFormat` +* `Action.AxisMenuPosition` +* `Action.AxisMenuRemove` +* `Action.AxisMenuRename` +* `Action.AxisMenuSort` +* `Action.AxisMenuTextWrapping` +* `Action.AxisMenuTimeBucket` +* `Action.CrossFilter` +* `Action.RemoveCrossFilter` + +For more information, see xref:embed-action-ref.adoc[Action reference]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: + +* `HostEvent.AddColumns` +* `HostEvent.OpenFilter` +* `HostEvent.RemoveColumn` +* `HostEvent.ResetSearch` +* `EmbedEvent.CrossFilterChanged` +* `EmbedEvent.DownloadAsPng` +* `EmbedEvent.VizPointRightClick` + +For more information, see xref:embed-events.adoc[Events]. + +|[tag redBackground]#DEPRECATED# a| + +The following events are deprecated from version 1.21.0 onwards. + +* `HostEvent.Download` + +* `EmbedEvent.Download` + +You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. + +For more information, see xref:embed-events.adoc[Events reference]. +|[tag orangeBackground]#MODIFIED# a| + +Events:: +The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. +Actions:: +Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: ++ +* `Action.DownloadAsCsv` +* `Action.DownloadAsPdf` +* `Action.DownloadAsXlsx` +* `Action.DownloadAsPng` + ++ +To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + + +** `Action.DownloadAsCsv` + +** `Action.DownloadAsPdf` + +** `Action.DownloadAsXlsx` + +** `Action.DownloadAsPng` + +|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: + +* `linkOverride` ++ +Allows overriding the *Open in new tab* link on embedded pages. + +* `contextMenuTrigger` ++ +Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. + +* `hideSearchBar` ++ +Allows hiding the Search bar on the embedded Search page. +|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. +For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. +|==== + +== Version 1.20.0, April 2023 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. +|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. +|==== + +== Version 1.19.0, February 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. +For more information, see xref:css-customization.adoc[Customize CSS]. +|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: + +[source,JavaScript] + +---- +liveboardEmbed.on(EmbedEvent.CustomAction, payload => { + if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { + console.log('Custom Action event:', payload.data); + } +}) +---- + +You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: + +* `HostEvent.Delete` +* `HostEvent.Download` +* `HostEvent.DownloadAsCsv` +* `HostEvent.DownloadAsXlsx` +* `HostEvent.ManagePipelines` +* `HostEvent.Save` +* `HostEvent.Share` +* `HostEvent.ShowUnderlyingData` +* `HostEvent.SpotIQAnalyze` +* `HostEvent.SyncToOtherApps` +* `HostEvent.SyncToSheets` + +For more information, see xref:events-hostEvents.adoc[Host events]. + +|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. + +For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. +|==== + +== Version 1.18.0, January 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + + +For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. + +|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + +For more information, see xref:css-customization.adoc[Customize CSS]. +|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + + +For more information, see xref:HostEvent.adoc#_gettml[GetTML]. + +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: + +* `Action.SyncToOtherApps` + +* `Action.SyncToSheets` + +* `Action.ManagePipelines` + + +You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. + +For more information, see xref:embed-action-ref.adoc[Actions]. +|==== + +== Version 1.17.1, December 2022 + +Bug fixes to the trusted authentication feature. + +== Version 1.17.0, November 2022 + +The new version of the SDK introduces several new features and enhancements. +[width="100%" cols="1,4"] +|==== +|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + + +* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + +* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + +* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + +This enhancement does not introduce any breaking changes to your current implementation. +|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + +For more information, see xref:embed-authentication.adoc[Authentication]. +|[tag greenBackground]#NEW FEATURE#| +The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + +For more information, see xref:css-customization.adoc[Customize CSS]. +|==== + +== Version 1.16.0, October 2022 + +The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. + +== Version 1.15.1, September 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + +For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. +|==== + +== Version 1.15.0, September 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. + +For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: + +* CopyLink +* CreateMonitor +* DownloadAsPdf +* Edit +* EditTML +* Explore +* ExportTML +* LiveboardInfo +* MakeACopy +* ManageMonitor +* Pin +* Present +* Remove +* Schedule +* SchedulesList +* UpdateTML + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.14.0, August 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + +For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. +|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. +The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. +|==== + +== Version 1.13.0, July 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. +|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + +For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. +|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + +This change does not impact your current embed implementation with `AuthType.SSO`. +|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.12.0, June 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. +|==== + +== Version 1.11.2, June 2022 + +Bug fix for Typescript builds that affect Angular project configurations. + +== Version 1.11.1, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. +|==== + +== Version 1.11.0, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: + +* `ALL` +* `AnswerChartSwitcher` +* `AnswerDelete` +* `CopyAEdit` +* `CopyToClipboard` +* `Download` +* `DownloadAsPdf` +* `DownloadAsCsv` +* `DownloadAsXlsx` +* `DrillExclude` +* `DrillInclude` +* `EditTML` +* `ExportTML` +* `Monitor` +* `Pin` +* `Save` +* `SaveAsView` +* `Share` +* `ShowUnderlyingData` +* `SpotIQAnalyze` +* `UpdateTML` +* `VizPointClick` + +For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. +|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. + +|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. +For more information, see xref:embed-actions.adoc[Show or hide UI actions]. +|==== + +== Version 1.10.4, May 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. +|==== +== Version 1.10.3, May 2022 + +Bug fix and improvements to the `logout` method. + +== Version 1.10.2, May 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. +|==== + +== Version 1.10.1, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. +|[tag orangeBackground]#MODIFIED# a| Note the following changes: + + +* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. +* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. +|==== + +== Version 1.10.0, April 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.9.8, April 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. + +For more information, see xref:full-embed.adoc[Embed full application]. +|==== + +== Version 1.9.6 and 1.9.7, April 2022 + +Bug fixes and improvements + +== Version 1.9.5, April 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. +For more information, see xref:locale-setting.adoc[Set locale and display language]. +|==== + +== Version 1.9.4, April 2022 + +Bug fixes and improvements to React components. + +== Version 1.9.3, March 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + +You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + +This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. + +For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. +|==== + +== Version 1.9.2, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. + +For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. +|==== + +== Version 1.9.1, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. + +For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. + +|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + + +* `LiveboardRendered` (EmbedEvent) + +For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.9.0, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: + +* `Action.AnswerDelete` + +* `Action.AnswerChartSwitcher` + +* `Action.AddToFavorites` + +* `Action.EditDetails` + + +For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.8.x, February 2022 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. +|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. +|==== + + +== Version 1.7.0, January 2022 + +[width="100%" cols="1,4"] +|==== +| +[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ + +The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. + +For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK includes the following new event: + +* `RouteChange` + +For more information, see xref:event-embedEvents.adoc[Events reference]. + +|==== + +== Version 1.6.x, November 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ + +You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. + +For more information, see xref:embed-actions.adoc[Show or hide UI actions]. + +|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ + +The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK supports the following new events: + +* `DialogOpen` +* `DialogClose` + +For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.5.0, October 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ + +The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. + +|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ + +The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. + +For more information, see xref:embed-search.adoc[Embed a pinboard]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK EmbedEvent library includes the following new events: + +* `VizPointDoubleClick` +* `Drilldown` +* `SetVisibleVizs` + +For more information, see xref:event-embedEvents.adoc[Events reference]. + +|==== + +== Version 1.4.0, September 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ + +The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. + +For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. + +|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ + +The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. + +For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. + +|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ + +The `appEmbed` SDK package includes the following new attributes: + +* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. + +* The `hideObjects` attribute to hide specific objects from a user's page view. + +For more information, see xref:full-embed.adoc[Embed full application]. + +|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ + +The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. + +For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. + +|[tag redBackground]#REMOVED# | + +The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. +|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ +The SDK EmbedEvent library includes the following events: + +* `QueryChanged` +* `AuthExpire` + +For more information, see xref:embed-events.adoc[Events and app integration]. +|==== + +== Version 1.3.0, August 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ + +The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: + +* `searchTokenString` ++ +A TML query string to define search tokens. + +* `executeSearch` ++ +When set to `true`, it executes search and shows the search results. + +For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. + +|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ + +The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. + +For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. + +|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ + +The SDK now supports logging in users automatically after a user session has expired. + +For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. + +|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ + +You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. +|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ + +* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. + +* The Answer payload for custom actions includes the following metadata: + +** `reportBookmetadata` ++ +Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. + +** user data ++ +Includes user information such as username, GUID of the user, and email address. + +To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. + +|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ + +The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. + +For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. +|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ + +You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. + +|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ + +The Visual Embed SDK now supports processing data in batches for callback custom action responses. +The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. + +For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. +|==== + +== Version 1.2.0, June 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ + +The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. + +For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ +The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. + +Pinboard:: +* Save +* Make a copy +* Add filters +* Configure filters +* Present +* Download as PDF +* Pinboard info +* Manage schedules + + +[NOTE] +Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. +|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ + +Visualizations on a pinboard: + +* Pin +* Download +* Edit +* Present +* Download as CSV +* Download as XLSX +* Download as PDF + +[NOTE] +Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. + +|==== + +== Version 1.1.0, May 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ + +When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. +To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. +|==== \ No newline at end of file From b6e4b52f11a65fea3d62493b907f9d5fa18649c7 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:15 +0530 Subject: [PATCH 16/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to rest-apiv2-changelog.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 1212 ++++++++++++++++-- 1 file changed, 1104 insertions(+), 108 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index db2225000..fa198c4aa 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -210,189 +210,1185 @@ Pinned Answer export:: // SOURCE: SCAL-236681, SCAL-306548 You can now export a pinned Answer directly from a Liveboard using the Answer report API. To export a pinned Answer, specify the `viz_guid` parameter in your API request. -Exports from this endpoint inherently reflect any row-level security (RLS) applied to the underlying data. +Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. ++ +To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter (conversational) Answers. + +Custom PNG dimensions:: +PNG exports now support custom dimensions via the following new parameters: ++ +* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. +* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. + +Display scaling:: +A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. +Valid range: 80–500%. + +Automatic file naming:: +The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). -Transient content export:: -// SOURCE: SCAL-306548 -You can now export a transient Answer using the Answer report API. To export a transient Answer, specify the `transient_content` parameter in your API request. +Contact ThoughtSpot support to enable these settings for PNG downloads on your ThoughtSpot instance. +For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. + +=== Share metadata API: Collections support [beta betaBackground]^Beta^ + +The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. + +To share a Collection, set `metadata_type` to `COLLECTION` in the request body. +For more information, see xref:collections.adoc#share-collection[Share a Collection]. == Version 26.5.0.cl, May 2026 -=== Spotter AI APIs +=== Sync connection metadata attributes +You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. + +=== Spotter APIs + +==== New API endpoints + +The following new endpoints allow sending messages to an active conversation +session with a Spotter agent. + +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + +Allows sending a message to an active Spotter AI conversation and returns a synchronous response. +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + +Allows sending to an active Spotter AI conversation and returns the response as a real-time Server-Sent Events (SSE) stream. + +These new endpoints replace the legacy agent conversation and SSE streaming APIs. + +==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# + +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + +Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + +These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. + +==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# + +The following enhancements have been introduced for the conversation creation operation workflow with the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint: + +metadata_context:: +To define the conversation context, the API request must include the `metadata_context` parameter with one of the following values: +* `AUTO_MODE`: Automatically discovers and selects the most relevant datasets for the user's queries. +* `DATA_SOURCE`: Sets the target context as the data source. You must specify at least one data source ID. +** To set a single data source object metadata context, specify a `data_source_identifier`. +** For multi-data source context, specify the `data_source_identifiers`. ++ [IMPORTANT] ==== -This release introduces breaking changes to Spotter agent APIs. The legacy `POST /api/rest/2.0/ai/conversation` endpoint and its related sub-endpoints (`/send-message`, `/create`, and `/delete`) are deprecated in 26.5.0.cl and replaced with new endpoints. + -Existing integrations using the deprecated endpoints will continue to function until the endpoints are removed in a future release. However, ThoughtSpot strongly recommends migrating to the new endpoints as soon as possible. For information about the new endpoints, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. +The `data_source` and `guid` attributes are deprecated in the 26.5.0.cl release version. Integrations using these parameters in ThoughtSpot versions 26.2.0.cl through 26.4.0.cl will continue to work until further notice. However, ThoughtSpot recommends using either `AUTO_MODE` or `DATA_SOURCE` with `data_source_identifier` or `data_source_identifiers` for the metadata context. ==== -New Spotter agent conversation API:: +Other context options:: +The `answer_context` and `liveboard_context` are removed and no longer supported. Any existing integration or embedding application passing `answer_context` or `liveboard_context` in the request body must update their workflows to use the `AUTO_MODE` or `DATA_SOURCE` option. -ThoughtSpot introduces the following new API endpoints for Spotter agent conversations. These endpoints replace the deprecated legacy conversation endpoints. +Enable save chat:: +The `enable_save_chat` parameter, when set to `true`, saves the conversation. -* `POST /api/rest/2.0/ai/agent/conversation/create` + -Creates a new Spotter agent conversation session. To save the conversation, set `enable_save_chat` to `true`. -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/converse` + -Sends a message to an active Spotter conversation session and returns the agent's response. -* `DELETE /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/delete` + -Deletes a Spotter agent conversation session and all its messages. +API response:: +The API response now returns the `conversation_identifier`, which is used in all +subsequent send message or SSE streaming calls. -For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. +=== Liveboard report API enhancements [beta betaBackground]^Beta^ +The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: -Deprecated Spotter AI endpoints:: -The following Spotter API endpoints are deprecated: +* `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. +* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. -* `POST /api/rest/2.0/ai/conversation/create` -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/send-message` -* `DELETE /api/rest/2.0/ai/conversation/{conversation_identifier}/delete` +For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. == Version 26.4.0.cl, April 2026 -[#version_26_4_0_cl_april_2026] +=== Variable API endpoints +The following endpoints are introduced for bulk delete and update operations for variables: -=== Variable API +* `POST /api/rest/2.0/template/variables/{identifier}/update-values` + +Assigns multiple values to a variable and sets the scope for variable values in a single API request. +* `POST /api/rest/2.0/template/variables/delete` + +Deletes one or more variables in a single API request. -The Variable REST API provides new API endpoints for the following bulk operations. +These new API endpoints replace the following legacy API endpoints deprecated in 26.4.0.cl. -Bulk deletion:: -You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. +* `POST /api/rest/2.0/template/variables/{identifier}/delete` +* `POST /api/rest/2.0/template/variables/update-values` -Batch update of variable values:: -You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. - -[NOTE] -==== -The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. -==== +Your existing implementation with the legacy API endpoints will continue to work until further notice. However, these endpoints will be removed from ThoughtSpot in a future release. Hence, we recommend updating your workflows to use the API endpoints at your earliest convenience. -For more information, see xref:variables.adoc[Variables]. +For more information, see xref:variables.adoc[Variable API documentation]. === Metadata parameterization +You can now parameterize multiple fields in a metadata object in a single API request using the `/api/rest/2.0/metadata/parameterize-fields` API endpoint. +This endpoint replaces the legacy `/api/rest/2.0/metadata/parameterize` endpoint, which is deprecated in 26.4.0.cl. -The `/api/rest/2.0/metadata/parameterize` endpoint is deprecated in 26.4.0.cl and later versions. Use the new `/api/rest/2.0/metadata/parameterize-fields` endpoint, which supports parameterizing multiple properties of metadata objects in a single API request. +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization API documentation]. -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization]. +=== Webhook integration +This release introduces the following features and enhancements to the webhook integration workflows: -=== Liveboard report API +Custom HTTP headers in webhook requests:: +Administrators can configure custom HTTP headers to send in webhook requests triggered by ThoughtSpot, in addition to the standard HTTP and authentication headers. You can specify these headers in the `additional_headers` attribute during webhook creation (`/api/rest/2.0/webhooks/create`) and update (`/api/rest/2.0/webhooks/{webhook_identifier}/update`) via REST APIs. -The Liveboard PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. +Webhook connection validation:: +You can now validate a webhook connection by sending a test payload via an API request to the `/api/rest/2.0/system/communication-channels/validate` endpoint. The API returns a response indicating the connection and authentication status for a given webhook connection. -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API]. +Webhook monitoring:: +To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. -=== Collections API [beta betaBackground]^Beta^ +For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. -The Collections REST API v2.0 allows creating, managing, and sharing *Collections* programmatically. Collections are organizational containers that allow grouping ThoughtSpot objects such as Liveboards, Answers, data models, tables, and other Collections. +=== Collections API endpoints -The following API endpoints are available for managing Collections: +The following APIs are introduced for Collections: -* `POST /api/rest/2.0/collections/create` + +* `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + Creates a new Collection. -* `POST /api/rest/2.0/collections/search` + -Returns a list of all Collections the authenticated user has access to. -* `PUT /api/rest/2.0/collections/{collection_identifier}/update` + -Updates the name, description, or content of an existing Collection. -* `DELETE /api/rest/2.0/collections/{collection_identifier}/delete` + -Deletes a Collection. +* `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + +Searches for a Collection in ThoughtSpot +* `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + +Updates an existing Collection +* `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + +Deletes a Collection For more information, see xref:collections.adoc[Collections]. -=== Webhook API enhancements +=== Email customization API enhancements + +The `template_properties` parameter now has the `hide_logo_url` elements for email template customization. Set it to `true` to entirely hide the logo component in the ThoughtSpot notification emails. + +=== Spotter API enhancements +Spotter AI APIs now support the following error responses: -* The `/api/rest/2.0/webhooks/create` endpoint includes new parameters for channel validation and custom HTTP headers. -* The `/api/rest/2.0/system/communication-channels/validate` endpoint is introduced for webhook channel validation. -* The `/api/rest/2.0/jobs/history/communication-channels/search` endpoint supports monitoring webhook delivery status. +* 401 Unauthorized: authentication token is missing, expired, or invalid. +* 403 Forbidden: the authenticated user does not have `CAN_USE_SPOTTER` privilege or view access to the underlying metadata sources. -For more information, see xref:webhooks-api.adoc[Webhooks API]. +=== Pivot table .xlsx exports +The following API endpoints now support pivot tables in `.xlsx` downloads with full visual and structural parity: + +* `POST /api/rest/2.0/report/answer` +* `POST /api/rest/2.0/schedules/create` + +To enable pivot formatting on your ThoughtSpot instance, contact ThoughtSpot Support. == Version 26.3.0.cl, March 2026 -[#_custom_access_token_api] -=== Custom access token API +=== Webhook APIs -The `filter_rules` parameter in the custom access token API is deprecated in 26.3.0.cl. This parameter was used to implement Attribute-Based Access Control (ABAC) via JWT tokens. +The Webhook API allows configuring Amazon S3 buckets as a storage destination for webhook payload delivery. -Existing implementations using `filter_rules` will continue to function until further notice. However, ThoughtSpot strongly recommends migrating to the new ABAC via RLS implementation that uses custom variables. For migration steps, see xref:abac-migration-guide.adoc[ABAC migration guide]. +* `POST /api/rest/2.0/webhooks/create` + +Configures storage destination for webhook delivery. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + +Allows modifying storage configuration for a webhook. +* `POST /api/rest/2.0/webhooks/search` + +Retrieves storage configuration details. -=== Object privilege API +=== Object privilege APIs +Administrators and users with edit access to data models can now use `/api/rest/2.0/security/metadata/manage-object-privilege` to assign object-level permissions to users and groups and control access to Spotter data model instructions. -The `/api/rest/2.0/security/metadata/manage-object-privilege` API endpoint is enhanced to support assigning `SPOTTER_COACHING_PRIVILEGE` to users and groups. This privilege grants access to Spotter coaching information without requiring data model editing or administration privileges. +To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. -=== Webhooks -Amazon S3 storage for webhook delivery:: -The following parameters are available in the `/api/rest/2.0/webhooks/create` and `/api/rest/2.0/webhooks/{webhook_identifier}/update` endpoints for configuring Amazon S3 storage as a webhook payload delivery destination: +=== User API enhancements + +The user APIs now support setting browser language as the default locale for ThoughtSpot users. Administrators can set the `use_browser_language` parameter as the default locale for ThoughtSpot users during the following API operations: + +* When creating a new user via `POST /api/rest/2.0/users/create` + +* When importing users via `POST /api/rest/2.0/users/import` + +* When updating user preferences via `POST /api/rest/2.0/users/{user_identifier}/update` + + +When set to `true`, a user's current locale preference is overridden and the browser's language takes precedence. + +The status of the browser language setting for a given user can also be retrieved using the following API endpoints: + +* `POST /api/rest/2.0/users/search` + +* `POST /api/rest/2.0/users/activate` + +* `GET /api/rest/2.0/auth/session/user` + -* `storage_type` — Set to `S3` to use Amazon S3 storage. -* `s3_config` — Contains the S3 bucket name, prefix path, and IAM role ARN for cross-account access. +=== Custom token generation API +Note the following changes to request parameters for the `/api/rest/2.0/auth/token/custom` API endpoint: -For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. +* The `filter_rules` parameter on the custom token authentication (`/api/rest/2.0/auth/token/custom`) page in the REST API Playground is no longer available for new configurations. Existing implementations that use `filter_rules` continue to work. However, we strongly recommend migrating to `variable_values` and ABAC via RLS for data security. + +* The `parameter_values` property is supported in the current release but will be deprecated in an upcoming version. Using `parameter_values` for row-level security will be phased out with this deprecation. Therefore, we recommend generating JWTs that pass data security attributes through formula variable attributes instead of `filter_rules` or `parameter_values` for ABAC. + +For more information, see xref:abac-migration-guide.adoc[ABAC JWT migration guide] and xref:abac_rls-variables.adoc[ABAC via RLS]. == Version 26.2.0.cl, February 2026 -=== Security settings API +=== 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 a 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. -The Security Settings REST API v2.0 allows administrators and developers to configure allowlists for Content Security Policy (CSP), Cross-origin Resource Sharing (CORS), and authentication attributes programmatically. +=== 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 following API endpoints are available: +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. -* `POST /api/rest/2.0/security/config/search` + -Returns the current security configuration at the cluster or Org level. -* `POST /api/rest/2.0/security/config/update` + -Updates the security configuration settings. +=== 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:security-settings.adoc[Security settings]. +For more information, see xref:data-report-v2-api.adoc[Data and Report APIs]. -=== Trusted authentication API +=== Email customization API enhancements -The `POST /api/rest/2.0/auth/token/custom` endpoint now supports configuring custom token attributes at the Org level. Administrators can use this endpoint to configure token validity, refresh settings, and other authentication properties. +The `template_properties` parameter now has two additional elements for email template customization: -=== Rate limits +* `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. -ThoughtSpot enforces rate limits on public REST API v2.0 requests. Rate limits are applied globally at the cluster level per client IP and affect all public API endpoints. +=== 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. -For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. +=== User API enhancements -== Version 10.15.0.cl, January 2026 +* `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 -ThoughtSpot introduces the following new REST API v2.0 endpoints for Spotter workflows: +This release introduces the following Spotter APIs: + +* `POST /api/rest/2.0/ai/instructions/set` + +Allows configuring natural language (NL) instructions on a data model to define how Spotter interprets queries, handles data nuances, and improves responses. +* `POST /api/rest/2.0/ai/instructions/get` + +Gets NL instructions that are currently assigned to a model. +* `POST /api/rest/2.0/ai/data-source-suggestions` + +Retrieves a list of recommended data sources based on the specified query string. + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +=== Variable APIs + +You can now create formula variables using the `/api/rest/2.0/template/variables/create` API endpoint, and assign values and scope to these variables using the `/api/rest/2.0/template/variables/update-values` API endpoint. + +For more information, see xref:variables.adoc[Configure variables]. + +=== ABAC tokens with formula variable attributes +The `/api/rest/2.0/auth/token/custom` API endpoint allows creating a token request with formula variables for ABAC via RLS implementation. + +For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +== Version 10.14.0.cl, November 2025 + +=== New API endpoints + + + +System:: +This release introduces the following endpoints for configuring communication channel preferences. + +* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + +Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. +* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + +Gets details of the communication channel preferences configured on ThoughtSpot. ++ +For more information, see xref:webhooks-lb-schedule.adoc#_configure_a_webhook_communication_channel[Configure communication channel settings]. + +Webhook:: +The following APIs are introduced for webhook CRUD operations: +* `POST /api/rest/2.0/webhooks/create` +Creates a webhook. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` +Updates the properties of a webhook. +* `POST /api/rest/2.0/webhooks/search` +Gets a list of webhooks configured in ThoughtSpot or in a specific Org. +* `POST /api/rest/2.0/webhooks/delete` +Deletes the webhook. ++ +For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. + +Column security rules:: + +* `POST /api/rest/2.0/security/column/rules/update` + +Updates column security rules for a given Table. + +* `POST /api/rest/2.0/security/column/rules/fetch` + +Gets details of column security rules for the tables specified in the API request. + +//// + +Spotter:: +POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse +//// +=== Variable API enhancements + +The variable API enhancements are listed in the following sections. For additional details, see xref:variables.adoc[Define variables]. + +==== Variable creation API + +* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. +* The `sensitive` parameter is renamed as `is_sensitive`. +//* You can define the data type for variables using the `data_type`property. +//* You can now create formula variables. To create a formula variable, use define the variable type as `FORMULA_VARIABLE` variable type in your API request . + +==== Variables update APIs [tag redBackground]#BREAKING CHANGE# + +The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/update-values`. + +To update the properties of a specific variable, use the `/api/rest/2.0/template/variables/{identifier}/update` endpoint and to assign values to one or several variables in a single API call, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. + +==== Variables search API + +* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. +* Filtering API response by `EDITABLE_METADATA_AND_VALUES` is no longer supported. + + +=== User API enhancements +The following APIs now support the `variable_values` parameter. The `variable_values` property can be used for user-specific customization. + +* `POST /api/rest/2.0/users/create` +* `POST /api/rest/2.0/users/search` +* `POST /api/rest/2.0/users/activate` + +=== DBT API enhancements +The `/api/rest/2.0/dbt/generate-tml` endpoint supports the `model_tables` attribute to list models and their tables. + +//// + +=== Authentication API +Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. + +//// + +== Version 10.13.0.cl, October 2025 + +=== New API endpoints + +Spotter:: + +* `POST /api/rest/2.0/ai/agent/conversation/create` + +Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + + + +* `POST /api/rest/2.0/ai/relevant-questions/` + +Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + + +//* `POST /api/rest/2.0/ai/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. + + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +Email customization:: +`POST /api/rest/2.0/customization/email/update` + +Updates an existing email customization. For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== API enhancements +The following APIs were modified to include new parameters: + +TML export:: +The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. + +Email customization:: +The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. + +For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== Deprecated endpoints + +Spotter:: +The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. + +Email customization:: +The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete`. + + +//// +=== Deprecated endpoints +The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. + +* `POST /api/rest/2.0/ai/conversation/create` +* `POST /api/rest/2.0/ai/analytical-questions` +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +//// + +== Version 10.12.0.cl, September 2025 + +=== New API endpoints + +The following API endpoints are now available: + +Custom calendar:: +* `POST /api/rest/2.0/calendars/create` + +Creates a custom calendar. +* `POST /api/rest/2.0/calendars/generate-csv` + +Exports a custom calendar in the CSV format. +* `POST /api/rest/2.0/calendars/search` + +Gets custom calendars for the connection ID specified in the API request. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + +Deletes a custom calendar. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + +Updates a custom calendar. + +Connection configuration:: +* `POST /api/rest/2.0/connection-configurations/create` + +Creates an additional configuration to an existing connection to a data warehouse. +* `POST /api/rest/2.0/connection-configurations/search` + +Gets the required connection configuration objects. +* `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + +Updates an existing connection configuration object. +* `POST /api/rest/2.0/connection-configurations/delete` + +Deletes the connection configuration object. + +=== Enhancements to APIs + +Export API endpoint:: + +* Answer TML: + +The `POST /api/rest/2.0/metadata/tml/export` API endpoint now allows fetching TML for Answer objects that do not have an ID or name assigned. The `session_identifier` and `generation_number` parameters allow you to define the session ID and the Answer generation number in the API request. These optional attributes can be used for unsaved Answers generated from Spotter queries. + +* Table TML: + +The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column security rules for Table TML objects. This attribute will export column security rules only if the object specified in the API request has column security applied and when `export_associated` is set to `true`. + +== Version 10.11.0.cl, July 2025 + +=== Search metadata API enhancements +The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: + +* The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. +* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. +* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. + + +=== System API +The API response generated from the `GET /api/rest/2.0/system/config-overrides` requests now returns the overrides in the `config_override_info` object. + +=== TML API +The API response for the `POST /api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/async/status` now includes the `author_display_name` property. This property shows the display name of user that initiated the asynchronous TML import request. + +=== REST API Java SDK + +The REST API Java SDK library artifacts are now available in the `com.thoughtspot` Maven namespace. If you are using Maven Central to import the REST API SDK artifacts, update the group ID in your `pom.xml` file to `com.thoughtspot` and the artifact ID to `rest-api-sdk`. + +For more information, see xref:rest-api-java-sdk.adoc#_import_the_sdk_to_your_application_environment[REST API Java SDK]. + +== Version 10.10.0.cl, July 2025 + +=== Email template customization APIs +This release introduces the following new endpoints for email template customization: + +* `POST /api/rest/2.0/customization/email` + +Allows you to personalize the ThoughtSpot notification emails content. +* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + +Removes the customizations done for the ThoughtSpot notification emails. +* `POST /api/rest/2.0/customization/email/search` + +Allows searching the email customization configuration if configured for ThoughtSpot. +* `POST /api/rest/2.0/customization/email/validate` + +Validates the email customization configuration if configured for ThoughtSpot. + +=== Group API + +The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: + +* `include_users` + +When set to `true`, it includes user details in the group search API response. +* `include_sub_groups` + +When set to `true`, it includes sub-groups in the group search response. + +=== Schedule API +You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: + +* `POST /api/rest/2.0/schedules/create` +To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. + +== Version 10.9.0.cl, June 2025 + +=== Metadata parameterization and content publishing across Orgs + +This release introduces the following new endpoints for metadata parameterization [beta betaBackground]^Beta^ and content publishing [beta betaBackground]^Beta^ across Orgs. To enable the content publishing feature and the related API operations on your instance, contact ThoughtSpot Support. + +* `POST /api/rest/2.0/metadata/parameterize` [beta betaBackground]^Beta^ + +Allows you to parameterize fields in metadata objects. +* `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + +Allows removing parameterization from fields in metadata objects +* `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + +Publish metadata objects to one or several Orgs on an instance. +* `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + +Removes published metadata objects from the Orgs specified in the API request. +* `POST /api/rest/2.0/template/variables/create` [beta betaBackground]^Beta^ + +Allows creating a template variable which can be used to parameterize fields in a metadata object. +* `POST /api/rest/2.0/template/variables/search` [beta betaBackground]^Beta^ + +Allows searching template variables +* `POST /api/rest/2.0/template/variables/{identifier}/update` [beta betaBackground]^Beta^ + +Allows updating properties of a template variable. +* `POST /api/rest/2.0/template/variables/update` [beta betaBackground]^Beta^ + +Allows you to add, remove, or replace properties of one or several template variables. +* `POST /api/rest/2.0/template/variables/{identifier}/delete` [beta betaBackground]^Beta^ + +Deletes a template variable. + +If your metadata objects are parameterized, you can use the `show_resolved_parameters` to filter the API response from `/api/rest/2.0/connection/search` and `/api/rest/2.0/metadata/search` endpoints to get only the objects with resolved parameterized values. + +=== Liveboard Report API +The Liveboard Report API now allows you to define the following properties: + +* `tab_identifiers` + +Optional parameter to specify the name or GUID of a Liveboard tab to export only the visualizations in that tab. +* `personalised_view_identifier` + +Optional parameter to specify the GUID of the Liveboard personalized view that you want to download. + +In addition to these parameters, you can also define the following properties for PNG downloads: + +* `image_resolution` +* `image_scale` +* `include_header` + +For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. + +=== REST API Java SDK + +The REST API Java SDK enables developers to interact programmatically with ThoughtSpot REST APIs from Java applications. It provides a client library with Java methods and classes that map to API endpoints, handle authentication, send API requests, and allow creating and modifying ThoughtSpot resources and objects. + +For information about how to install and use the SDK, see xref:rest-api-java-sdk.adoc[Java SDK for REST APIs]. + + +== Version 10.8.0.cl, April 2025 + +=== New API endpoints + +This version introduces the following endpoints: +//// +* `POST /api/rest/2.0/ai/analytical-questions` + +Allows using an existing ThoughtSpot Answer or Liveboard, and include content to improve query response. +//// + +* `POST /api/rest/2.0/metadata/update-obj-id` + +Update object IDs for given metadata objects. + + +[NOTE] +==== +An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. +Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. +==== + +=== Metadata API + +* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: + +** `include_discoverable_objects` + +Allows including Answers and Liveboards that are marked as discoverable by the object owner. +** `metadata_obj_id` + +Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. + +=== TML APIs + +* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. + +* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. + +=== Report APIs +The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. + +For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. + +== Version 10.6.0.cl, March 2025 + +=== New metadata API endpoints + +* `POST /api/rest/2.0/metadata/headers/update` + +Updates metadata header for a given list of objects. +* `POST /api/rest/2.0/metadata/worksheets/convert` + +Converts a Worksheet object to a Model. + +=== Report APIs +[tag redBackground]#BREAKING CHANGE# + +Downloading Liveboard reports in the CSV and XLSX file format via `POST /api/rest/2.0/report/liveboard` API endpoint is not supported. The CSV and XLSX `file_format` options have been removed because they were not functioning in the expected manner. + +==== Parameters for regional settings + +The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow users to define the following `regional_settings` attributes: + +* `currency_format` +* `user_locale` +* `number_format_locale` +* `date_format_locale` + +//// +=== Custom authentication token API + +The `/api/rest/2.0/auth/token/custom` API endpoint now allows you to define the `reset_option` to specify if the attributes assigned to the token should persist or be reset. +//// + +=== Custom object ID in TML and Metadata APIs + +The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: + +* `POST /api/rest/2.0/metadata/search` +* `POST /api/rest/2.0/metadata/headers/update` +* `POST /api/rest/2.0/metadata/tml/export` + + +=== TML import API + +The `/api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/import` endpoints allow skipping diff check when processing TMLs for imports. The `skip_diff_check` attribute is disabled by default and can be enabled to avoid importing objects that do not have any changes. + +=== API response changes + +The 200 and 201 response body from `POST /api/rest/2.0/ai/answer/create` and `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API calls now includes the `display_tokens` property. + + +== Version 10.5.0.cl, December 2024 + +=== Custom access token API +The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: + +* `auto_create` + +Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. +* `REPLACE` enum for `persist_option` + +Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +=== TML import APIs + +TML async import:: + +The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: ++ +* `import_policy` + +Allows you to specify if all objects should be imported during the TML import operation. Valid values are: + +** `PARTIAL_OBJECT` (default) +** `PARTIAL` +** `VALIDATE_ONLY` +** `ALL_OR_NONE` + +* `enable_large_metadata_validation` + +Indicates if the TMLs with large and complex metadata should be validated before the import. ++ +For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +//// +* `skip_diff_check` + +Allows skipping checks that find differences in TML content before processing TML objects for import. +//// + +TML import API:: + +The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. + +TML export API:: + +The `/api/rest/2.0/metadata/tml/export` endpoint now allows you to include additional attributes when exporting TML for an object from ThoughtSpot. The `export_options` allows you to include the following optional attributes: + +* `include_obj_id_ref` + +Specifies whether to export `user_defined_id` of the referenced object. This setting is valid only if the `UserDefinedId` property in TML is enabled. +* `include_guid` + +Specifies whether to export the GUID of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. +* `include_obj_id` + +Specifies whether to export the `user_defined_id` of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. + + +Share metadata:: + +The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. + +Role API:: + +The `/api/rest/2.0/roles/create` API endpoint now allows setting `read_only` attribute to specify if the role is read only. A read-only role cannot be updated or deleted. + +== Version 10.4.0.cl, November 2024 + +=== New API endpoints + +Spotter AI APIs [beta betaBackground]^Beta^ :: -Send a query to Spotter:: * `POST /api/rest/2.0/ai/conversation/create` + -Creates a new Spotter conversation session. -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/send-message` + -Sends a query to an active Spotter conversation and returns the agent's response. -* `DELETE /api/rest/2.0/ai/conversation/{conversation_identifier}/delete` + -Ends and deletes a Spotter conversation session. +Creates a conversation session. +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + +Generates responses for user queries and follow-up questions. +* `POST /api/rest/2.0/ai/answer/create` + +Generates an Answer from a Natural Language Search query. + +Authentication:: +The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. + ++ +ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. + +Connections:: +The following new API endpoints are available for updating and deleting a connection object: + +* `POST /api/rest/2.0/connections/{connection_identifier}/update` +* `POST /api/rest/2.0/connections/{connection_identifier}/delete` + ++ +ThoughtSpot recommends using these APIs instead of `POST /api/rest/2.0/connection/update` and `POST /api/rest/2.0/connection/delete`. + +TML:: +The following API endpoints are available for asynchronous TML import: + +* `POST /api/rest/2.0/metadata/tml/async/import` + +Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects. +* `POST /api/rest/2.0/metadata/tml/async/status` + +Fetches task status for the async TML import operations. + +For more information, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +=== API enhancements + +User session:: + +* The 200 API response for the `/api/rest/2.0/auth/session/user` and `/api/rest/2.0/users/search` is modified to show `access_control_properties`. + +* You can now manage account activation status for IAMv2 users using the following API endpoints: + +** `POST /api/rest/2.0/users/create` + +** `POST /api/rest/2.0/users/{user_identifier}/update` + +//// +TML import API:: +You can specify the following attributes in TML import requests to `/api/rest/2.0/metadata/tml/import`: + +* `skip_cdw_validation_for_tables` + +Indicates if the Cloud Data Warehouse (CDW) validation for table imports should be skipped. +//// + +Report API:: + +The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: + +* `session_identifier` + +Session ID returned in API response by the `/api/rest/2.0/ai/answer/create` or `/api/rest/2.0/ai/conversation/create` endpoint. +* `generation_number` + +Number assigned to the Answer session with Spotter. ++ +If you are downloading an Answer generated by Spotter, you must specify the session ID. The `metadata_identifier` property is not required. + +=== Deprecated features + +Connection APIs:: + +The following connection API endpoints are deprecated: + +* `POST /api/rest/2.0/connection/delete` +* `POST /api/rest/2.0/connection/update` + ++ +Use `POST /api/rest/2.0/connections/{connection_identifier}/update` and `POST /api/rest/2.0/connections/{connection_identifier}/delete` APIs to update and delete a connection object respectively. + +Authentication:: + +The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated. ++ +ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` API endpoint with `filter_rules` and `parameter_values` to configure user properties for ABAC via tokens. + +== Version 10.3.0.cl, October 2024 + +=== New API endpoint + +You can now create a copy of a Liveboard or Answer object using `/api/rest/2.0/metadata/copyobject` API endpoint. + +== Version 10.1.0.cl, August 2024 + +=== New API endpoints + +* `POST /api/rest/2.0/metadata/tml/export/batch` + +Exports a batch of TML for user, user group, or Role objects. + +=== Security APIs +The `/api/rest/2.0/security/metadata/fetch-permissions` API endpoint supports the following parameters: + +* `record_offset` + +Specifies the starting record number from which the records for each metadata type will be included in the API response. +* `record_size` + +Specifies the number of records that should be included for each metadata type in the API response. +* `permission_type` + +Specifies the type of permission. Valid values are: +** `EFFECTIVE` - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong. +** `DEFINED` - If a user or user group received access to metadata objects via object sharing by another user. + +== Version 10.0.0.cl, July 2024 + +=== Roles + +You can now assign the `CAN_MANAGE_VERSION_CONTROL` role using any of the following API endpoints: + +* `POST /api/rest/2.0/roles/create` +* `POST /api/rest/2.0/roles/{role_identifier}/update` + +The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration with ThoughtSpot. + +== Version 9.12.0.cl, May 2024 + +==== New features + +Authentication API:: + +* `/api/rest/2.0/auth/token/validate` + +Validates the authentication token of the logged-in user. + +TML API:: +The export TML API requests now support the following parameters: ++ +* `export_schema_version` + +Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set `export_schema_version` to `v2`. + +* `export_dependent` + +Allows exporting dependent Tables while exporting a Connection. +* `export_connection_as_dependent` + +Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. + +==== Deprecated features + +Token authentication APIs:: + +The `jwt_user_options` object property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated. Use the `user_parameters` property to define security entitlements to a user session. For more information, see xref:abac-user-parameters.adoc[ABAC via token][beta betaBackground]^Beta^. + +== Version 9.10.5.cl, April 2024 + +=== New features + +Authentication:: + +The `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints support generating JWT token for Attribute-Based Access Control. The `user_parameters` object allows you to define security entitlements for a given user. + +For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +Roles:: + +The `/api/rest/2.0/roles/create` and `/api/rest/2.0/roles/{role_identifier}/update` API endpoints support assigning the following privileges to a Role for granular data access control and management: + +* `CAN_MANAGE_CUSTOM_CALENDAR` +* `CAN_CREATE_OR_EDIT_CONNECTIONS` +* `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` + +DBT:: + +You can now use `file_content` to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the `/api/rest/2.0/dbt/dbt-connection`, `/api/rest/2.0/dbt/generate-tml`, `/api/rest/2.0/dbt/generate-sync-tml`, and `/api/rest/2.0/dbt/update-dbt-connection` endpoints. This field is required if the `import_type` parameter is set to `'ZIP_FILE'`. + +Connections:: + +* `/api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + +Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot. +* `/api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + +Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot. + +Logs:: +The `/api/rest/2.0/logs/fetch` API endpoint allows fetching all logs in a single API request. To get all logs, set `get_all_logs` to `true`. + +Share metadata:: + +The `/api/rest/2.0/security/metadata/share` API supports the following new properties: + +* `notify_on_share` + +Sends a share notification to the email addresses specified in the API request. +* `has_lenient_discoverability` + +Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only. + +Users:: +The `trigger_activation_email` property allows you to specify if an activation email must be sent to the user's email address in the user creation request to the `/api/rest/2.0/users/create` endpoint. + +=== Deprecated features + +Version Control APIs:: + +The following parameters in `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` are deprecated from 9.10.5.cl onward: + +* `default_branch_name` + +Replaced by `commit_branch_name` +* `guid_mapping_branch_name` + +Replaced by `configuration_branch_name` -Configure NL instructions on a model:: -* `PUT /api/rest/2.0/ai/nl-instructions/update` + -Sets natural language (NL) instructions on a data model to coach the Spotter system. -* `GET /api/rest/2.0/ai/nl-instructions` + -Retrieves the NL instructions configured on a data model. +For more information, see xref:version_control.adoc[Git integration and version control]. -For more information, see xref:spotter-apis.adoc[Spotter APIs]. +== Version 9.10.0.cl, March 2024 -=== Variable API +=== New API endpoints -* `POST /api/rest/2.0/template/variables/create` + -Creates a new variable. -* `POST /api/rest/2.0/template/variables/search` + -Returns a list of variables. -* `PUT /api/rest/2.0/template/variables/{identifier}/update` + -Updates a variable. -* `DELETE /api/rest/2.0/template/variables/{identifier}/delete` + -Deletes a variable. _(Deprecated in 26.4.0.cl — use `/api/rest/2.0/template/variables/delete` instead.)_ -* `PUT /api/rest/2.0/template/variables/update-values` + -Assigns values to variables. _(Deprecated in 26.4.0.cl — use `/api/rest/2.0/template/variables/{identifier}/update-values` instead.)_ +DBT:: -For more information, see xref:variables.adoc[Variables]. +* `POST /api/rest/2.0/dbt/dbt-connection` + +Creates a DBT connection. +* `POST /api/rest/2.0/dbt/generate-tml` + +Generates Worksheets and Tables for a given DBT connection. +* `POST /api/rest/2.0/dbt/generate-sync-tml` + +Synchronizes the existing TML of data models and Worksheets and imports them to ThoughtSpot. +* `POST /api/rest/2.0/dbt/search` + +Gets a list of DBT connection objects for a given user or Org. +* `POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + +Updates a DBT connection. + +System:: + +`GET api/rest/2.0/system/banner` + +Gets cluster maintenance status and banner text. + ++ +For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[Cluster maintenance and upgrade]. + +== Version 9.8.0.cl, January 2024 + +The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. + +== Version 9.7.0, November 2023 + +=== Version Control APIs + +This release introduces the following enhancements to the Version Control API endpoints: + +==== Git connection creation and update APIs + +The `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints include the following enhancements: + +New parameters:: + +* `commit_branch_name` + +Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using `commit_branch_name` instead of `default_branch_name` in the API calls to prevent users from committing changes to the default deployment branch. +* `configuration_branch_name` + +Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the `configuration_branch_name` property is defined, the `guid_mapping_branch_name` parameter is not required. + +Modified parameters:: +The `enable_guid_mapping` parameter is enabled by default. + +Separate branches for Orgs:: +If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git `repository_url`, the `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints do not support configuring the same branch name for these Orgs. + +Deprecation notice:: + +The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. + +For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. + +==== Commit API + +The `POST /api/rest/2.0/vcs/git/branches/commit` API endpoint allows the following new attribute in the request body: + +* `delete_aware` ++ +When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation. + +For more information, see xref:version_control.adoc#_commit_files_and_changes[Commit files]. + +==== Deploy API + +Note the following changes: + +* The `branch_name` attribute is now mandatory in the `POST /api/rest/2.0/vcs/git/commits/deploy` API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org. + +* After a successful deployment, a tracking file is generated with the `commit_id` and saved in the Git branch that is used for storing configuration files. The `commit_id` recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls. + +For more information, see xref:version_control.adoc#_deploy_commits[Deploy commits]. + +=== User API + +The following new API endpoints are introduced for user account management: + +* `POST /api/rest/2.0/users/activate` + +Activates an inactive user account. + +* `POST /api/rest/2.0/users/deactivate` + +Deactivates a user account. + +=== Support for sorting of columns at runtime +The following data API endpoints now support runtime sorting of columns: + +* `POST /api/rest/2.0/searchdata` + +* `POST /api/rest/2.0/metadata/liveboard/data` + +* `POST /api/rest/2.0/metadata/answer/data` + + +For more information, see xref:runtime-sort.adoc[Runtime sorting of columns]. + +== Version 9.6.0.cl, October 2023 + +=== New API endpoints + +* `POST /api/rest/2.0/customization/custom-actions/search` + +Gets custom action objects +* `POST /api/rest/2.0/customization/custom-actions` + +Creates a custom action +* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + +Updates the properties of a custom action object. +* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + +Deletes a custom action + +=== SDK for TypeScript + +ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk?activeTab=readme[NPM site, window=_blank]. + +== Version 9.5.0.cl, September 2023 + +=== New API endpoints for Role-Based Access Control [beta betaBackground]^Beta^ + +* `POST /api/rest/2.0/roles/search` + +Gets details of role objects available in the ThoughtSpot system. +* `POST /api/rest/2.0/roles/create` + +Creates a role and assigns privileges +* `POST /api/rest/2.0/roles/{role_identifier}/update` + +Updates the properties of a given role +* `POST /api/rest/2.0/roles/{role_identifier}/delete` + +Removes a role object from the ThoughtSpot system + +For more information, see xref:roles.adoc[Role-based access control]. + +[NOTE] +==== +The roles APIs work only if the Role-Based Access Control (RBAC) [beta betaBackground]^Beta^ feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support. +==== + +=== Enhancements and API modifications + +Support for runtime parameter overrides:: +The following data and report API endpoints support applying runtime parameter overrides: +* `POST /api/rest/2.0/searchdata` + +* `POST /api/rest/2.0/metadata/liveboard/data` + +* `POST /api/rest/2.0/metadata/answer/data` + +* `POST /api/rest/2.0/report/liveboard` + +* `POST /api/rest/2.0/report/answer` + +Git integration support for Orgs:: + +The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for `dev`, `staging`, and `prod` and integrate these environments with a GitHub repo. + ++ +For more information, see xref:version_control.adoc[Git integration and version control]. + +=== Response code change [tag redBackground]#BREAKING CHANGE# + +The following endpoints now return the 204 response code instead of 200. The 204 code does not return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues. + +* `POST /api/rest/2.0/connection/delete` +* `POST /api/rest/2.0/connection/update` +* `POST /api/rest/2.0/users/{user_identifier}/update` +* `POST /api/rest/2.0/users/{user_identifier}/delete` +* `POST /api/rest/2.0/users/change-password` +* `POST /api/rest/2.0/users/reset-password` +* `POST /api/rest/2.0/users/force-logout` +* `POST /api/rest/2.0/groups/{group_identifier}/update` +* `POST /api/rest/2.0/groups/{group_identifier}/delete` +* `POST /api/rest/2.0/metadata/delete` +* `POST /api/rest/2.0/orgs/{org_identifier}/update` +* `POST /api/rest/2.0/orgs/{org_identifier}/delete` +* `POST /api/rest/2.0/schedules/{schedule_identifier}/delete` +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +* `POST /api/rest/2.0/security/metadata/assign` +* `POST /api/rest/2.0/security/metadata/share` +* `POST /api/rest/2.0/system/config-update` +* `POST /api/rest/2.0/tags/{tag_identifier}/update` +* `POST /api/rest/2.0/tags/{tag_identifier}/delete` +* `POST /api/rest/2.0/tags/assign` +* `POST /api/rest/2.0/tags/unassign` +* `POST /api/rest/2.0/vcs/git/config/delete` +* `POST /api/rest/2.0/auth/session/login` +* `POST /api/rest/2.0/auth/session/logout` +* `POST /api/rest/2.0/auth/token/revoke` + + +== Version 9.4.0.cl, August 2023 + +=== API endpoints to schedule and manage Liveboard jobs + +* `*POST* /api/rest/2.0/schedules/create` + +Creates a scheduled job for a Liveboard +* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/update` + +Updates a scheduled job +* `*POST* /api/rest/2.0/schedules/search` + +Gets a list of Liveboard jobs configured on a ThoughtSpot instance +* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/delete` + +Deletes a scheduled job. + +For more information, see link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fschedules%2Fsearch-schedule[REST API v2.0 Reference]. + +=== API to fetch authentication token + +The `GET /api/rest/2.0/auth/session/token` API endpoint fetches the current authentication token used by the currently logged-in user. + +=== Version Control API enhancements + +* The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance: + +** `*POST* /api/rest/2.0/vcs/git/config/create` +** `*POST* /api/rest/2.0/vcs/git/config/update` + +=== User and group API enhancements + +* The `**POST** /api/rest/2.0/users/{user_identifier}/update` and `**POST** /api/rest/2.0/groups/{group_identifier}/update` support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the `operation` type as `REMOVE` in the API request. +* The `**POST** /api/rest/2.0/users/{user_identifier}/update` allows you to define locale settings, preferences, and other properties for a user object. + +== Version 9.3.0.cl, June 2023 + +The following Version Control [beta betaBackground]^Beta^ API endpoints are now available for the lifecycle management of content on your deployment environments: + +* `*POST* /api/rest/2.0/vcs/git/config/search` +* `*POST* /api/rest/2.0/vcs/git/commits/search` +* `*POST* /api/rest/2.0/vcs/git/config/create` +* `*POST* /api/rest/2.0/vcs/git/config/update` +* `*POST* /api/rest/2.0/vcs/git/config/delete` +* `*POST* /api/rest/2.0/vcs/git/branches/commit` +* `*POST* /api/rest/2.0/vcs/git/commits/{commit_id}/revert` +* `*POST* /api/rest/2.0/vcs/git/branches/validate` +* `*POST* /api/rest/2.0/vcs/git/commits/deploy` + +For more information, see xref:version_control.adoc[Version control and Git integration]. + +== Version 9.2.0.cl, May 2023 + +New endpoints:: + +* System ++ +** `POST /api/rest/2.0/system/config-update` + +Updates system configuration ++ +** `GET /api/rest/2.0/system/config-overrides` + +Gets system configuration overrides + +* Connections ++ +** POST /api/rest/2.0/connection/create + +Creates a data connection + +** `POST /api/rest/2.0/connection/search` + +Gets a list of data connections + +** `POST /api/rest/2.0/connection/update` + +Updates a data connection + +** `POST /api/rest/2.0/connection/delete` + +Deletes a data connection + +Enhancements:: + +* Support for runtime filters and runtime sorting of columns + +The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_apply_runtime_filters_in_rest_api_v2_requests[runtime filters] and xref:runtime-sort.adoc[sorting column data]: ++ +** `POST /api/rest/2.0/report/liveboard` + +** `POST /api/rest/2.0/report/answer` + +* Search users by their favorites ++ +The `/api/rest/2.0/users/search` API endpoint allows searching users by their favorite objects and home Liveboard setting. + +* Ability to log in to a specific Org ++ +The `/api/rest/2.0/auth/session/login` API endpoint now allows ThoughtSpot users to log in to a specific Org context. -=== Intercept API calls +== Version 9.0.0.cl, February 2023 -The `interceptUrls` attribute in the Visual Embed SDK allows intercepting API calls from the embedded ThoughtSpot application. Embed events are enhanced to support the `EmbedEvent.ApiIntercept` event, which fires when an API call matching the specified conditions is detected. +The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: -For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. +* xref:rest-api-v2.adoc[REST API v2.0] +* xref:rest-api-v2-getstarted.adoc[Get started with REST API v2.0] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison] From 960721946187e9c92efb8781ffa94b36688bd95a Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:17 +0530 Subject: [PATCH 17/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to embed-spotter.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] --- modules/ROOT/pages/embed-spotter.adoc | 405 ++++++++++++++++++++------ 1 file changed, 314 insertions(+), 91 deletions(-) diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index 0c04f8377..eaaf2b1a0 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -198,153 +198,376 @@ When Auto mode is enabled, **Preview data** and **Data Model instructions** opti Spotter 3 experience is available with a new prompt interface that includes additional features and user elements to enrich your Spotter experience. -To enable the new chat interface, set the `newChatInterface` flag to `true`: +To enable the new chat interface in your embed, set the `updatedSpotterChatPrompt` attribute: [source,JavaScript] ---- const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - frameParams: { width: '100%', height: '100%' }, - worksheetId: '<%=datasourceGUID%>', - newChatInterface: true, + // ...other embed configuration attributes + // Enable the updated Spotter chat prompt experience. + updatedSpotterChatPrompt: true, }); -spotterEmbed.render(); ---- -// ============================================================ -// [#_enable_file_upload_in_spotter_chat] anchor preserved from previous version -// ============================================================ -[#fileUpload] -== Enable file upload in Spotter chat -// SOURCE: SCAL-299746 (SDK 1.49.0) -You can allow your embedded users to upload files directly in the Spotter chat panel. To enable this feature, set `spotterFileUploadEnabled` to `true` in the `SpotterChatViewConfig` object. +[.widthAuto] +[.bordered] +image::./images/spotter3-new-interface.png[Spotter 3 new interface] + +==== Chat history panel + +You can also include the *Chat history* panel to allow your users to access the chat history from their previous sessions. + +To enable chat history features, set the `enablePastConversationsSidebar` attribute to `true`. Additionally, you can customize the appearance and contents of the chat history panel using the configuration parameters available in the xref:SpotterSidebarViewConfig.adoc[`SpotterSidebarViewConfig`] interface and the xref:SpotterEmbedViewConfig.adoc#_spottersidebarconfig[spotterSidebarConfig] object. + +[source,JavaScript] +---- +import { + SpotterEmbed, + SpotterEmbedViewConfig, + SpotterSidebarViewConfig +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new SpotterEmbed('#tsEmbed', { + // ...other embed view configuration options + // Configuration for the Spotter sidebar UI + spotterSidebarConfig: { + enablePastConversationsSidebar: true, // Show chat history sidebar + spotterSidebarTitle: 'My Conversations', // Update the title of the sidebar + spotterSidebarDefaultExpanded: true, // Expand Spotter chat history sidebar by default on load + }, +}) +---- + +[NOTE] +==== +The standalone `enablePastConversationsSidebar` attribute is deprecated in v1.47.0 and can no longer be used to enable or disable the chat history. +==== + + +==== Chat history panel + +To enable and customize the chat history sidebar, configure the chat history properties in the `spotterSidebarConfig` object: [source,JavaScript] ---- const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - frameParams: { width: '100%', height: '100%' }, + // ... worksheetId: '<%=datasourceGUID%>', - spotterChat: { - spotterFileUploadEnabled: true, - // Optionally restrict allowed file types: - // spotterFileUploadFileTypes: ['csv', 'xlsx'], + spotterSidebarConfig: { + enablePastConversationsSidebar: true, // Enable the chat history sidebar + spotterSidebarDefaultExpanded: true, // Expand the sidebar by default + spotterSidebarTitle: 'Chat History', // Custom sidebar header text + spotterNewChatButtonTitle: 'New Conversation', // Custom label for the New chat button + spotterChatRenameLabel: 'Rename session', // Custom label for the Rename action + spotterChatDeleteLabel: 'Delete session', // Custom label for the Delete action + spotterConversationsBatchSize: 20, // Conversations fetched per batch (default: 30) + spotterDocumentationUrl: 'https://your-help-center-url', // Custom best practices link }, }); -spotterEmbed.render(); ---- -// ============================================================ -// SOURCE: SCAL-310399, SCAL-312622, SCAL-293483, SCAL-314448 -// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl -// ============================================================ +[NOTE] +==== +The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use the `enablePastConversationsSidebar` property within the `spotterSidebarConfig` object instead. When both properties are defined, the value in `spotterSidebarConfig` takes precedence. +==== -[#spotter-analysts] -== Spotter Analysts [earlyAccess eaBackground]#Early Access# -[.version-badge.new]#New# Visual Embed SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl +==== 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. -// TODO: [WRITER] Confirm EA vs GA status with Agents Experience team (Karamveer Singh) before publishing. -// TODO: [WRITER] Add a screenshot of the Analysts sidebar panel once available from the design team. +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. -Spotter Analysts are dedicated Spotter agent configurations scoped to a specific data model and skill set. When the Analysts feature is enabled on your ThoughtSpot instance, the Spotter sidebar displays an *Analysts* section where users can select an Analyst to start a focused conversation. +[NOTE] +==== +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. +==== -In ThoughtSpot Embedded, the Analysts section is **disabled by default**. You can enable the feature by configuring the relevant settings on your ThoughtSpot instance, then control and customize the Analysts experience using the SDK configuration options described in this section. +Currently, the Visual Embed SDK does not provide any attributes or action IDs to hide these elements. As a workaround, you can use CSS selectors to hide these elements: -=== Configure Analyst labels +[source,JavaScript] +---- +init({ + 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 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]. + +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] +---- +// Initialize the SDK with CSS variables with custom style definitions +init({ + // ... + customizations: { + style: { + // Use CSS variables to customize styles + customCSS: { + variables: { + "--ts-var-button--primary-background": "#008000", + "--ts-var-spotter-prompt-background": "#F0EBFF", + "--ts-var-root-color": "#E3D9FC", + "--ts-var-root-background": "#F7F5FF", + }, + }, + }, + }, +---- + +==== Customizing 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. -Use `spotterAnalystLabel` and `spotterAnalystsLabel` in `SpotterSidebarViewConfig` to customize the text labels shown in the Analysts sidebar. +[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", + } + } + } +}); +---- + +=== 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] +---- + 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" + } + }); +---- + +The following figures show the customized Spotter icon: +[.widthAuto] +[.bordered] +image::./images/spotter-icon-customization.png[Spotter icon customization] + +=== Hiding the Spotter icon and ThoughtSpot branding from the chat interface +To hide the Spotter logo and branding in the chat interface, use the following parameters in the `SpotterChatViewConfig` interface: + +* `hideToolResponseCardBranding` + +When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. + +* `toolResponseCardBrandingLabel` + +Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. + +Example:: ++ [source,JavaScript] ---- import { SpotterEmbed, - AuthType, - init, + SpotterEmbedViewConfig, + SpotterChatViewConfig } from '@thoughtspot/visual-embed-sdk'; -init({ - thoughtSpotHost: 'https://your-thoughtspot-host', - authType: AuthType.TrustedAuthTokenCookieless, - getAuthToken: () => fetch('/api/token').then(r => r.json()).then(d => d.token), -}); +spotterChatConfig: { + // Hide the default logo and label on tool response cards in Spotter chat UI + hideToolResponseCardBranding: true, + // Set a custom label to display as the branding on tool response cards + toolResponseCardBrandingLabel: 'CompanyName', +} +---- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - frameParams: { width: '100%', height: '100%' }, - worksheetId: '<%=datasourceGUID%>', - spotterSidebar: { - spotterAnalystLabel: 'Assistant', // Custom singular label; default: "Analyst" - spotterAnalystsLabel: 'My Assistants', // Custom section header; default: "Analysts" +[#fileUpload] +=== Allowing file uploads in Spotter chats +To enable file uploads in the Spotter chat panel: + +. Ensure that `spotterFileUploadEnabled` is set to `true` in the `spotterChatConfig` object. This setting enables ** + Add files** option in the Spotter chat panel. +. Optionally, you can restrict the types of files users can upload by specifying the file types in the `SpotterFileUploadFileTypes` array. If no file format is specified, all supported file types are allowed for uploads. + +[source,JavaScript] +---- +const embed = spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + //... + spotterChatConfig: { + spotterFileUploadEnabled: true, + spotterFileUploadFileTypes: { types: ['pdf', 'png', 'xlsx'] }, }); - -spotterEmbed.render(); ---- -=== Control Analyst actions +[#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: -// TODO: [WRITER] Verify the following Action enum values exist in the SDK 1.51.0 release -// of types.ts before publishing. Source: SCAL-312622 Jira description. -// Run: grep -n "Analyst" src/types.ts in the tagged SDK 1.51.0 release. +[source,JavaScript] +---- + // 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]. -Use `disableActions` or `hideActions` with the following Analyst-specific action IDs to control which actions are available to users in the Analysts panel: -[width="100%", cols="2,4"] -[options="header"] -|==== -|Action ID |Description -|`Action.ShowAnalysts` |Controls the visibility of the Analysts section in the sidebar. -|`Action.CreateAnalyst` |Controls the *Create* action for creating a new Analyst. -|`Action.EditAnalyst` |Controls the *Edit* action for modifying an existing Analyst. -|`Action.MakeCopyAnalyst` |Controls the *Make a copy* action. -|`Action.ShareAnalyst` |Controls the *Share* action for sharing an Analyst with other users. -|`Action.DeleteAnalyst` |Controls the *Delete* action. -|==== +== Code samples -Example — hide the Create and Delete Analyst actions: +**Code sample for embedding Spotter Classic and Spotter 2 experience** [source,JavaScript] ---- import { SpotterEmbed, - Action, + SpotterEmbedViewConfig, + SpotterChatViewConfig, AuthType, init, -} from '@thoughtspot/visual-embed-sdk'; + prefetch, + EmbedEvent, + HostEvent +} +from '@thoughtspot/visual-embed-sdk'; -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - frameParams: { width: '100%', height: '100%' }, - worksheetId: '<%=datasourceGUID%>', - hideActions: [ - Action.CreateAnalyst, - Action.DeleteAnalyst, - ], +// 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 }); -spotterEmbed.render(); ----- +//Define event handler to show a loading indicator when the embed is initializing. +function showLoader() { + // Show loading indicator +} -[#_enable_starter_prompts] -=== Enable starter prompts +// Define event handler to hide the loading indicator when the embed has loaded. +function hideLoader() { + // Hide loading indicator +} -// SOURCE: src/embed/conversation.ts — SpotterChatViewConfig.enableStarterPrompts -// SOURCE: SCAL-293483, SCAL-314448 +// 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 + //... other configuration attributes + }); + + // 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); + }); +} +---- -Use the `enableStarterPrompts` property in `SpotterChatViewConfig` to show onboarding starter prompts when the Spotter interface loads. Starter prompts are AI-generated question suggestions based on the connected data model, helping first-time users discover what they can ask. +**Code sample for embedding Spotter 3 experience** [source,JavaScript] ---- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - frameParams: { width: '100%', height: '100%' }, - worksheetId: '<%=datasourceGUID%>', - spotterChat: { - enableStarterPrompts: true, // Default: false - }, +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 }); -spotterEmbed.render(); +//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 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 'auto_mode' + updatedSpotterChatPrompt: true, // Enable new chat interface + enablePastConversationsSidebar: true, // Enable chat history + //... other configuration attributes + }); + + // 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); + }); +} ---- -[NOTE] -==== -Starter prompts are generated based on the data model connected to the Spotter session. The suggestions reflect fields and measures available in the connected Model, View, or Table. + -// TODO: [WRITER] Verify whether customStarterPrompts (from SpotterVizConfig) is also supported in SpotterEmbed for overriding the generated prompts, or whether it is LiveboardEmbed/AppEmbed only. -==== +== Additional resources +* 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] From 5797b8d7b1bc948c5e6669c9c76acb079a247108 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:18 +0530 Subject: [PATCH 18/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to full-app-customize.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] --- modules/ROOT/pages/full-app-customize.adoc | 359 ++++++++++++++++++--- 1 file changed, 307 insertions(+), 52 deletions(-) diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 55b693b5f..4baddff9f 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -26,8 +26,8 @@ The classic V1 and V2 navigation and homepage experience modes are deprecated as ThoughtSpot application supports the following UI experience modes: * xref:full-app-customize.adoc#_upgrade_to_the_v3_experience[V3 navigation and home page experience] (__Recommended__) -* xref:full-app-customize.adoc#_upgrade_from_the_v2_experience_to_v3_experience[V2 navigation and home page experience] [.version-badge.deprecated]#Deprecated# as of 26.8.0.cl -* Classic (V1) experience [.version-badge.deprecated]#Deprecated# as of 26.8.0.cl +* xref:full-app-customize.adoc#_upgrade_from_the_v2_experience_to_v3_experience[V2 navigation and home page experience] +* Classic (V1) experience (__Default experience__) The key differences between these UI experience modes are listed in the following table: @@ -40,13 +40,9 @@ The key differences between these UI experience modes are listed in the followin |Feature component |Classic (V1) experience | V2 experience | V3 experience |**UI experience**| Classic layout + -Includes a standard top navigation, pages without a left navigation panel, and a static home page with limited customization options. +Includes a standard top navigation, pages without a left navigation panel, and a static home page with limited customization options.| Improved look and feel + -[.version-badge.deprecated]#Deprecated# as of 26.8.0.cl| Improved look and feel + - -Includes a modular home page with customizable components, an application selector menu, and a left navigation panel for each application context. - -[.version-badge.deprecated]#Deprecated# as of 26.8.0.cl | Modern look and feel + +Includes a modular home page with customizable components, an application selector menu, and a left navigation panel for each application context. | Modern look and feel + Includes a left navigation panel that dynamically adjusts its menu based on context and a modular home page with enhanced visual elements and customizable components. |**Navigation experience**| Top navigation includes the application menu. + @@ -85,46 +81,6 @@ Before updating the UI experience, review the xref:full-app-customize.adoc#_ui_e For more information about the layout and UI elements in the V3 experience, refer to the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage[ThoughtSpot Product Documentation, window=_blank]. -[#nav-v1-v2-deprecation] -=== V1 and V2 deprecation in 26.8.0.cl [.version-badge.deprecated]#Deprecated# - -// SOURCE: SCAL-312731 -// TODO: [WRITER] Confirm with the SDK team whether SDK params PrimaryNavbarVersion.V1/V2 and -// HomePage.V1/V2 were valid enum values in previous SDK releases, or whether these -// modes were always activated by omitting the discoveryExperience object entirely. -// Update this section accordingly to avoid confusing readers who never used enum values -// for V1/V2. - -Starting from ThoughtSpot Cloud 26.8.0.cl, the V3 navigation and homepage experience is the default for all ThoughtSpot Embedded sessions. The V1 and V2 experience modes are deprecated and will be removed in a future release. - -**What changed:** - -* All embedded sessions render in V3 experience mode by default, even if the `discoveryExperience` object is not set in the SDK configuration. -* Embedding configurations that previously relied on V1 (classic) behavior by omitting `discoveryExperience` may now render in V3 mode automatically. -* The `discoveryExperience` object remains the recommended way to configure the V3 experience explicitly and ensure stable behavior across future releases. - -**Recommended migration action:** - -Update your embed configuration to explicitly set `discoveryExperience` if you have not already done so: - -[source,JavaScript] ----- -import { AppEmbed, HomePage, PrimaryNavbarVersion } from '@thoughtspot/visual-embed-sdk'; - -const embed = new AppEmbed('#embed', { - discoveryExperience: { - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation - homePage: HomePage.ModularWithStylingChanges, // Enable V3 home page - }, - showPrimaryNavbar: true, - // ... other config -}); - -embed.render(); ----- - -Setting `discoveryExperience` explicitly ensures your embed is not affected by future default-behavior changes. For a full migration guide, see xref:full-app-customize.adoc#_upgrade_to_the_v3_experience[Upgrade to the V3 experience]. - === Upgrade to the V3 experience If you are using the classic (V1) experience in your embed, ThoughtSpot recommends migrating directly to the V3 experience for an improved user interface, enhanced home page customization options, and navigation controls. @@ -187,7 +143,306 @@ const embed = new AppEmbed("#embed", { ---- ==== Upgrade from the V2 experience to V3 experience -// TODO: [WRITER] Retain the existing V2-to-V3 upgrade content from the previous version of this file. -// This section was truncated during the patch due to file size. Reapply from the 26-8-0-doc-updates branch source. -// TODO: [WRITER] Run a diff between this file and 26-8-0-doc-updates/modules/ROOT/pages/full-app-customize.adoc -// to ensure all existing sections below this point are preserved. +Both V2 and V3 experience modes support a modular home page with customizable components. The V3 modular home page experience includes additional improvements to the Watchlist, Trending, Learning, and Favorites panels. + +To upgrade your UI to the V3 experience, set `homePage` to `HomePage.ModularWithStylingChanges`: + +[source,JavaScript] +---- +// Import required components and enums for V3 experience +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + HomePage, // Enum for home page experience settings + PrimaryNavbarVersion // Enum for V3 navigation experience +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + // Enable V3 navigation and home page experience + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience + homePage: HomePage.ModularWithStylingChanges, // Enable V3 modular home page + }, + // Show navigation panels + showPrimaryNavbar: true, + //... other embed view configuration attributes +}); +---- + +[#_enable_the_v4_focused_home_page_experience] +=== Enable the V4 focused home page experience + +The V4 focused home page experience is available with Visual Embed SDK v1.50.0 and ThoughtSpot Cloud 26.7.0.cl. This experience consolidates the **Watchlist** and **Recents** sections into a unified, focused view designed to surface the most relevant content for users. + +[IMPORTANT] +==== +The focused home page experience is an Early Access feature and is disabled by default. To enable this feature, contact your ThoughtSpot administrator. +==== + +To enable the V4 focused home page, set `homePage` to `HomePage.Focused` in the `discoveryExperience` object: + +[source,JavaScript] +---- +// Import required components and enums +import { + AppEmbed, + HomePage, // Enum for home page experience settings + PrimaryNavbarVersion // Enum for V3 navigation experience +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience + homePage: HomePage.Focused, // Enable V4 focused home page experience + }, + showPrimaryNavbar: true, + //... other embed view configuration attributes +}); +---- + +==== Post migration checks +After you enable the V3 experience: + +* Ensure the UI shows the V3 navigation and home page. + +//// ++ +The following figure shows the user interface with the V3 experience: ++ +[.bordered] +[.widthAuto] +image::./images/new-nav3.png[New home page] +//// +* Verify that all the customization settings are applied correctly. +* If you have set up custom routes for navigation within your embedded app, verify navigation workflows and check for breaking changes. + +//// +=== Upgrade from classic (V1) experience to V2 experience +Setting `modularHomeExperience` to `true` in the SDK enables the V2 experience. + +[source,javascript] +---- +const embed = new AppEmbed("#embed", { + // Enable the V2 experience + modularHomeExperience: true, + //... other view config attributes +}); +---- + +[NOTE] +==== +The V2 experience will be deprecated in an upcoming release. ThoughtSpot strongly recommends upgrading to the V3 experience to ensure continued support and access to the latest features. +==== + +The following figure shows the user interface with the V2 experience enabled: + +[.bordered] +[.widthAuto] +image::./images/homepage.png[New home page] +//// + +=== UI customization options and resulting experience + +The following table summarizes the resulting UI experience for different configuration combinations: + +[div boxAuto] +-- +[width="100%", cols="6,7,6"] +[options='header'] +|=== +|`discoveryExperience` setting| `modularHomeExperience` state | Resulting UI experience +a| +[source,JavaScript] +---- +discoveryExperience: { + // V3 experience and navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // V3 modular home page + homePage: HomePage.ModularWithStylingChanges + } +---- +|`true` / `false` + +Not set / Incorrect +| V3 navigation and V3 modular home page + +a| +[source,JavaScript] +---- +discoveryExperience: { + // V3 experience and navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // V4 home page experience + homePage: HomePage.Focused + } +---- +|`true` / `false` + +Not set / Incorrect +| V3 navigation and V4 home page experience + +a| +[source,JavaScript] +---- +discoveryExperience: { + // V3 navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // modular home page + homePage: HomePage.Modular + }, +---- +|`true` / `false` + +Not set / Incorrect + +| V3 navigation and a modular home page that is similar to the V2 experience + +a| +[source,JavaScript] +---- +discoveryExperience: { + // V3 navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding + }, +---- +|`true` / `false` + +Not set / Incorrect +|V3 navigation and a modular home page that is similar to the V2 experience + +a| + +[source,JavaScript] +---- +discoveryExperience: { + // modular home page + homePage: HomePage.Modular + }, +---- +|`true` / `false` + +Not set / Incorrect + +| V2 navigation and V2 modular home page +a| + +[source,JavaScript] +---- +discoveryExperience: { + // V3 modular home page + homePage: HomePage.ModularWithStylingChanges + }, +---- +a|`true` +| V2 navigation and V2 modular home page + +a| + +[source,JavaScript] +---- +discoveryExperience: { + // V3 modular home page + homePage: HomePage.ModularWithStylingChanges + }, +---- +a| `false` / Not set / incorrect +|Classic (V1) experience. + +a| Not set +a|`true` | V2 navigation and V2 modular home page + +a| Not set a|`false` / Not set / incorrect | Classic (V1) experience + +a| +[source,JavaScript] +---- +discoveryExperience: { + // V3 navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // V4 modular home page + homePage: HomePage.Focused + }, +---- +a|`false` +| V3 navigation and V4 home page experience +|=== +-- + + +== Customize navigation experience + +For information about the navigation elements in each UI experience mode and the related customization settings in the SDK, see xref:customize-nav-full-embed.adoc[Customize navigation experience]. + +== Customize home page experience +For information about the home page components and the related customization settings in the SDK, see xref:customize-homepage-full-embed.adoc[Customize home page experience]. + +== Customize the default loading page and navigation routes +In full application embedding, the home page is set as the default landing page when the embedded app loads. You can xref:set-default-page.adoc[customize the default landing page settings] using the `pageId` or `path` attribute. + +== Customize list page experience +A list page in ThoughtSpot refers to a page that displays a list of objects, such as Answers, Liveboards, and Liveboard schedules. The list pages include columns for sorting, filtering, tagging, sharing, or deleting objects. + +=== List layouts +If your embed has the V3 navigation and homepage experience enabled, the ListPage v3 experience will be enabled by default. + +The list layouts in full app embedding typically include columns such as *Name*, *Author*, *Favorites*, *Tags*, *Last Viewed* and more. For Liveboard lists, a *Verified* column is available to filter the list by verified objects. In addition to these columns, the ListPage v3 experience includes the **Views** column and the following enhancements: + +* Sorting options for **Name**, **Author**, and **Views** columns. +* Filter addition by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. + +=== Include or exclude columns from list layouts +To customize the columns in list pages such as *Liveboards* and *Answers*, use the xref:AppViewConfig.adoc#_hiddenlistcolumns[hiddenListColumns] attribute with the following List page IDs: + +* `ListPageColumns.Author` to show or hide the *Author* column. +* `ListPageColumns.DateSort` to show or hide the *Last modified* column. +* `ListPageColumns.Favorites` to show or hide the *Favorites* column. +* `ListPageColumns.Share` to show or hide the *Share* links in the column. +* `ListPageColumns.Tags` to show or hide the *Tags* column. +* `ListPageColumns.Verified` to show or hide the *Verified* column in Liveboard lists. + +The following example hides specific columns using the `hiddenListColumns` array: + +[source,javascript] +---- +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + ListPageColumns // Enum for columns on list pages +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + // hide Author, Share, and Tags columns on Answers and Liveboards listing pages + hiddenListColumns: [ + ListPageColumns.Author, + ListPageColumns.Share + ], + //... other view config attributes + +}); +---- + +[NOTE] +==== +The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but doesn't remove the *Share* button that appears above the list on selecting an object. To hide both the column and the *Share* button, use xref:Action.adoc#_share[Action.Share] in the `hiddenActions` array. +==== + +== Additional customization controls +xref:css-customization.adoc[CSS customization] allows overriding default styles in ThoughtSpot application pages. You can also use xref:theme-builder.adoc[Theme Builder] to explore the available CSS variables. + +If there is a page element you cannot hide using ThoughtSpot or Visual Embed SDK options, you can use a CSS selector to target the element and apply CSS properties such as `display: none`;, `visibility: hidden`;, or `height: 0px` to hide it from the UI. To find the appropriate selector, use your browser’s *Inspect* tool to examine the style element in the *Elements* section of the browser's Developer Tools. + +[source,css] +---- +.bk-data-scope .left-pane .header-lt { + display: none !important; + visibility: hidden !important; +} +---- + +An example of using direct selectors in a file is available in the link:https://github.com/thoughtspot/custom-css-demo/blob/main/complete.css[complete.css sample, target=_blank] on the ThoughtSpot GitHub repository. + +You can also declare direct selectors using the xref:css-customization.adoc#_css_rules_using_selectors[rules] property in the Visual Embed SDK configuration. This is useful for real-time testing, especially in the Visual Embed SDK playground. Note the required format for encoding CSS rules as JavaScript objects. + + +== Additional resources + +* xref:full-embed.adoc[Embed full application] +* xref:page-navigation.adoc[Create dynamic menus and navigation] +* xref:AppViewConfig.adoc[AppViewConfig reference page] +* xref:HostEvent.adoc[Host events] +* xref:EmbedEvent.adoc[Embed Events] + + From fb4b2330c573418f36f344553b782acdcf03a594 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:19 +0530 Subject: [PATCH 19/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to security-settings.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] --- modules/ROOT/pages/security-settings.adoc | 404 +++++++++++++++++++--- 1 file changed, 364 insertions(+), 40 deletions(-) diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 84d6bb4a9..01b02b423 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -122,73 +122,397 @@ Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` [source,cURL] ---- curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ - -H 'Authorization: Bearer {token}' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Content-Type: application/json' \ - -d '{ + --data-raw '{ + "cluster_preferences": { + "csp_settings": { "visual_embed_hosts": [ - "https://your-host-domain.com" + "www.thoughtspot.com", + "mysite.com:8080", + "http://localhost:8080" ] - }' + } + } + }' ---- -// ============================================================ -// SOURCE: SCAL-320438 -// New section: Custom-scheme allowlisting for mobile/hybrid apps -// TODO: [WRITER] Confirm the exact list of supported custom schemes (capacitor://, -// ionic://, others?) with Prashant Borkar / SmartApp-TSE team. -// TODO: [WRITER] Confirm which CSP allowlist field accepts custom-scheme URLs — verify -// with the platform team whether visual_embed_hosts is the correct field, or -// whether a separate field is required. -// TODO: [WRITER] Confirm whether the REST API security-settings/configure endpoint -// accepts custom-scheme URLs in the visual_embed_hosts array without validation errors. -// ============================================================ +[#csp-connect-src] +==== 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. -[#custom-scheme-allowlisting] -==== Custom-scheme allowlisting for mobile and hybrid apps +. On your ThoughtSpot application instance, go to *Develop* page. +. If your instance has Orgs, click the *All Orgs* tab. +. Go to *Customizations* > *Security settings*. +. Click *Edit*. +. 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*. -[.version-badge.new]#New# ThoughtSpot Cloud 26.8.0.cl -Mobile and hybrid applications built with frameworks such as Capacitor or Ionic use custom URL schemes (for example, `capacitor://localhost` or `ionic://localhost`) as their application origin. To embed ThoughtSpot in these applications, you must add the custom scheme to the CSP Visual Embed Hosts allowlist. +*Through the REST API v2* -[WARNING] -==== -*Security caveat:* Allowlisting a shared app scheme such as `capacitor://localhost` does **not** uniquely identify your specific application. Any application using the same framework presents the same origin to the browser. + +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. -Treat custom-scheme allowlisting as a mechanism to enable embedding functionality, **not** as an access-control boundary. Security for these embeds must be enforced through authentication — use xref:trusted-auth-sdk.adoc[trusted authentication tokens] rather than relying on origin-based access control. -==== +[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 + +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. + +. On your ThoughtSpot application instance, go to *Develop* page. +. If your instance has Orgs, click the *All Orgs* tab. +. Go to *Customizations* > *Security settings* and configure the settings: + + +* *CSP img-src domains* + +Add the domains from which you want to load images and favicons. +* *CSP font-src domains* + +Add the domains from which you want to load fonts. +* *CSP style-src domains* + +Add the domains from which you want to load stylesheets. +* *CSP script-src domains* +Add the domains from which you want host scripts. For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. + +//// +* *CSP frame-src domains* + +Add the iframe source URL 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": [ + "*" + ] + } +} +}' +---- -To add a custom scheme to the CSP Visual Embed Hosts allowlist: + +==== 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. . If your instance has Orgs, click the *All Orgs* tab. . Go to *Customizations* > *Security settings*. . Click *Edit*. -. In the *CSP visual embed hosts* text box, add your custom scheme URL. For example: -+ +. In the *Permitted iFrame domains* text box, add the domain URL of the website or portal that you want to use for iFrame content. +. 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] ---- -capacitor://localhost -ionic://localhost +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 + +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. + +The CORS configuration on your instance controls which domains can access and modify your application content. To allow your application to call ThoughtSpot or its REST API endpoints, and request resources, you must add your application domain to the CORS allowlist. For example, if your website is hosted on the `example.com` domain and the embedded ThoughtSpot content is hosted on the `example.thoughtspot.com`, you must add the `example.com` domain to the CORS allowlist for cross-domain communication. You can also add `\http://localhost:8080` to the CORS allowlist to test your deployments locally. However, we recommend that you disable `localhost` access in production environments. + +If you enable CORS for your application domain, ThoughtSpot adds the `Access-Control-Allow-Origin` header in its API responses when your host application sends a request to ThoughtSpot. + +To add domain names to the CORS allowlist, follow these steps: + +. On your ThoughtSpot instance, navigate to the *Develop* page. +. If your instance has Orgs, you can configure CORS allowlists for all Orgs globally at the cluster-level or per Org. + + +* For cluster-wide configuration, click the *All Orgs* tab. +* To configure settings at the Primary Org level, click the *Primary Org* tab. +* To configure CORS settings at the Org-level, switch the Org context via Org switcher in the top navigation bar. + +. On *Develop* page, go to *Customizations* > *Security settings*. +. Click *Edit*. +. 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`. Include the custom-scheme URL in the `visual_embed_hosts` array: +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 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ - -H 'Authorization: Bearer {token}' \ - -H 'Content-Type: application/json' \ - -d '{ - "visual_embed_hosts": [ - "capacitor://localhost", - "https://your-host-domain.com" - ] - }' +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 + +[IMPORTANT] +==== +[#port-protocol] + +* You can add multiple domains to the CORS and CSP Visual Embed allowlists on the **Develop** **Customizations** > **Security Settings** page. Ensure that the CORS and CSP allowlists do not exceed 4096 characters. +* *Protocol in the domain URL*: +** CSP hosts — The UI allows adding a domain URL with or without the protocol (`http/https`). However, to avoid long URLs in the CSP header, you can exclude the protocol in the domain URL strings. +** CORS hosts — The UI allows adding a domain URL with the protocol (`http/https`). If the domain URLs are using `https`, you can exclude the protocol in domain URL strings, because ThoughtSpot assigns `https` to the URLs by default. +** For localhost and non-HTTPS URLs — For non-HTTPs domains or localhost such as `localhost:3000`, if you add the domain without the protocol, the `https` protocol will be assigned to the URL by default. Due to this, the localhost domain with `http` (`\http://localhost:3000`) might result in a CSP or CORS error. Therefore, include the `http` protocol in the domain name strings for non-HTTPS domains and localhost. +* **Port**: If your domain URL has a non-standard port such as 8080, specify the port number in the domain name string. +* **Websocket endpoints**: + +You can add Websocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. Only hosts explicitly listed with `wss://` are permitted. +==== + +The following table shows the valid domain name strings for the CORS and CSP allowlists. + +[width="100%" cols="4,2,2,2,2"] +[options='header'] +|==== +|Domain name format|CSP Visual Embed host|CSP connect-src |CORS |CSP font-src + +CSP style-src + +CSP img-src + +a|Domain URL strings without protocol + +* `thoughtspot.com` +* `www.thoughtspot.com` + + +|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported + +a|Domain URL strings for localhost + +* `localhost` +* `localhost:3000` +* `\http://localhost:8080` +* `\http://localhost:3000` + +|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported +a|Domain URL strings without port + +* `thoughtspot.com` +* `mysite.com` + +If your domain URL has a non-standard port, for example `mysite.com:8080`, make sure you add the port number in the domain name string. + +|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported +|Wildcard (`\*`) , (`.*`) for domain URL + + |[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported a|[tag orangeBackground tick]#✓# Partial support + + +__Supports only (`.*`)__ |[tag greenBackground tick]#✓# Supported +|Wildcard +++(*)+++ before the domain name extension + +`\https://*.com`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported +|Plain text string without the domain name extension. + + +`thoughtspot` |[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported# |[tag redBackground tick]#x# Not supported + +|Domain name with wildcard (*) and a leading dot + + +`+++.*.thoughtspot.com +++` + +|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported a|[tag greenBackground tick]#✓# Supported + + +__To avoid domain validation errors, make sure you add an escape character `\` after the wildcard in the domain URL string:__ + +`.*\.thoughtspot.com` +|[tag redBackground tick]#x# Not supported + +a|Wildcard before the domain name + + +`+++*+++.thoughtspot.com` + +|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported |[tag redBackground tick]#x# Not supported |[tag greenBackground tick]#✓# Supported + + +a| Domain names with space, backslash (\), and wildcard (*). + +* `www.+++*+++.+++*+++.thoughtspot.com` + +* `www.thoughtspot.com/*` + +* `thoughtspot .com` + +|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported +|URLs with query parameters + +`\http://thoughtspot.com?2rjl6`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported +|URLs with path parameters + +`thoughtspot.com/products`|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported |[tag redBackground tick]#x# Not supported |[tag greenBackground tick]#✓# Supported +|URLs with path and query parameters + +`thoughtspot.com/products?id=1&page=2`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported +|IPv4 addresses + +`255.255.255.255`|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported +|Semicolons as separators + +`thoughtspot.com; thoughtspot.com;`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported +|Comma-separated values + +`thoughtspot.com, thoughtspot.com`|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported +|`mail://xyz.com`|[tag redBackground tick]#x# Not supported |[tag redBackground tick]#x# Not supported 2*|[tag redBackground tick]#x# Not supported +a|+++Wildcard (*) for port+++ + +`thoughtspot:*`|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported +a|Websocket URLs + +`wss://`| [tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported |[tag redBackground tick]#x# Not Supported| [tag greenBackground tick]#✓# Supported +| +|==== + + +=== 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]. + +*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: + +. On your ThoughtSpot application instance, go to *Develop* page. +. If your instance has Orgs, click the *All Orgs* tab. +. Go to *Customizations* > *Security settings*. +. Click *Edit*. +. Turn on the *Enable partitioned cookies* toggle switch. +. Click *Save changes*. + +With partitioned cookies enabled, when a user logs in to ThoughtSpot and accesses embedded content on a host application, a cookie is set with the partitioned attribute. On browsers supporting partitioned cookies, the partitioned cookie will persist in the app after a successful login. + +[IMPORTANT] ==== -Custom scheme strings are case-sensitive. Ensure the scheme string in the allowlist exactly matches the origin your application uses, including the trailing path component if applicable. +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. ==== + +*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 +To enable or disable trusted authentication at the cluster or Org level, send a request to the `POST /api/rest/2.0/auth/configure` endpoint. + +To find the trusted authentication configuration for the specified auth type at the cluster or Org level, send a request to the `POST /api/rest/2.0/auth/search` endpoint. + +For more information on the trusted authentication configuration through APIs, see xref:authentication.adoc[Configuring authentication settings]. + +See xref:trusted-authentication.adoc[Trusted authentication] and xref:_secret_key_management[Secret key management] for other related information. + + + +== 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" +}' +---- From f537cae7f01e3f16d0e8e58920e34b3987482562 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:20 +0530 Subject: [PATCH 20/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to tml.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] --- modules/ROOT/pages/tml.adoc | 399 +++++++++++++++++++++++++++++++++--- 1 file changed, 367 insertions(+), 32 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 84bf60c88..b8b39c0fd 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -125,7 +125,7 @@ You can import single or multiple objects using the `tml/import` API. If you are By default, the `fqn` parameter is not present in the TML file. However, you can export TML with FQNs and use it during the import. -You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven't been changed since the last import or TML update, and eliminates importing redundant objects. +You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven’t been changed since the last import or TML update, and eliminates importing redundant objects. To import TML representation of the metadata objects into ThoughtSpot, use one of the following API endpoints: @@ -172,57 +172,392 @@ You can import TML objects asynchronously by scheduling TML import tasks via `PO |Form parameter|Description| Default |`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ |`create_new` + -__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects.| `false` -|`import_policy` + -__Optional__ |__String__. Policy to import TML objects. + -Valid values are `PARTIAL`, `ALL_OR_NONE`, `VALIDATE_ONLY`, and `PARTIAL_OBJECT`. |`PARTIAL` -|`all_orgs_override` + -__Optional__ |__Boolean__. When set to `true`, the TML objects are imported in all Orgs.| `false` -|`skip_cdw_validation_for_tables` + -__Optional__|__Boolean__. When set to `true`, skips CDW validation for Table TMLs.| `false` +__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. | `false` +|`all_orgs_context` + +__Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. + +__Requires Org administration privileges to access TML objects across all Orgs.__| `false` + +|`import_policy` a|__String__. Available from 10.5.0.cl. Policy to follow during import. The allowed values are: + +* `PARTIAL` + +Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. +* `ALL_OR_NONE` + +Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. +* `VALIDATE_ONLY` + +Validates the objects but does not import them. +* `PARTIAL_OBJECT` + +Imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. +| `PARTIAL_OBJECT` + |`skip_diff_check` + -__Optional__|__Boolean__. When set to `true`, skips diff check for TML import. | `false` +__Optional__ +|__Boolean__. When set to `true`, skips the diff check before processing TML objects for import. By default, ThoughtSpot compares each TML object against its last imported version and skips objects that have not changed, which reduces unnecessary reimports. Set to `true` to bypass this check and reimport all objects regardless of whether they have changed. |`false` +|`enable_large_metadata_validation` + +__Optional__ + |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). +|`false` +|==== +//// + + +|`skip_cdw_validation_for_tables` + +__Optional__ |__Boolean__. Skips Cloud Data Warehouse validation for table TML imports. | `false` +//// +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/import' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_tmls": [ + "{\\\"guid\\\": \\\"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\\\",\\\"liveboard\\\": {\\\"name\\\": \\\"Total Sales\\\",\\\"visualizations\\\": [{\\\"id\\\": \\\"Viz_1\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total quantity purchased, Total sales by region\\\",\\\"description\\\": \\\"test\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[region] [quantity purchased] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total quantity purchased\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"region\\\",\\\"Total quantity purchased\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"region\\\"],\\\"y\\\": [\\\"Total quantity purchased\\\",\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"f6701821-5630-49cd-b26f-f98bebb4e98e\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total quantity purchased\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"1e086aef-236d-4cf0-8909-9e04e04a1ac4\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": true}},{\\\\\\\"id\\\\\\\": \\\\\\\"7be648d3-c791-43e4-bb13-63fea808f326\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"region\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total quantity purchased\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"b8b38851-5980-40a1-bd88-608b7a9c6e86\\\"},{\\\"id\\\": \\\"Viz_2\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales in a year\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [store] [date].monthly [date].'\''this year'\''\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Month(date)\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"store\\\",\\\"Month(date)\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"LINE\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"Month(date)\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"store\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"feb33c4a-614b-4623-9d12-1c4cf2250801\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"e89293cb-d10a-40d5-b787-81be33cc8b81\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Month(date)\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"6a4acb32-9036-4d4c-a830-f2b06966a322\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"39e5242e-43d0-4ef7-8673-73b12433e0c5\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (85226)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (86001)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (91006)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (94702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80301)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#8C62F5\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80920)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FF8142\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06110)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#ABC7F9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06854)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B5ECF2\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"delaware (19702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FDE9AF\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30022)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#9BE5CB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30329)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#D1C0FB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"idaho (83704)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFCCB3\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60062)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2359B6\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60642)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#369FAA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"indiana (46250)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#BF982A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"iowa (50266)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#049160\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"maryland (21045)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#6A4ABA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (01701)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#C26232\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (02215)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (48103)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#82DFE9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (49512)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCD977\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55369)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#56D3A8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55420)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B094F8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"missouri (63144)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFA97E\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59106)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#163772\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59718)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#22636B\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89052)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#785F1A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89145)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#025B3C\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new hampshire (03860)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#422E75\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new jersey (07936)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#7A3D1F\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"7efc7b0e-e680-44a4-ba9c-3bd5d7272367\\\"},{\\\"id\\\": \\\"Viz_3\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by item type and region\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [item type] [region]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"item type\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"item type\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"item type\\\",\\\"region\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"STACKED_COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"item type\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"item type\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"region\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"a330db6d-3714-4b5f-aed7-cca5ab679502\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"96ac1ce3-7efd-455e-a569-2cd0792b5f95\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"item type\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"92153012-664c-458e-9a74-6138c5030838\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"east\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"midwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"south\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"southwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"west\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"9de47a0e-6f20-40ba-9a52-3374ee530f09\\\"},{\\\"id\\\": \\\"Viz_4\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by state\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[state] [store] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"state\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"state\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"state\\\",\\\"store\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"GEO_AREA\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"state\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"state\\\"],\\\"y\\\": [\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"e4943da4-f159-470c-836b-7c6c55d59c2f\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"b99d582a-b215-4381-89ad-280c451979e3\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"state\\\\\\\"]}}],\\\\\\\"systemMultiColorSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"colorMap\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"state\\\\\\\",\\\\\\\"color\\\\\\\": [\\\\\\\"#ffffb2\\\\\\\",\\\\\\\"#fddd87\\\\\\\",\\\\\\\"#fba35d\\\\\\\",\\\\\\\"#f75534\\\\\\\",\\\\\\\"#f9140a\\\\\\\",\\\\\\\"#d70315\\\\\\\",\\\\\\\"#b10026\\\\\\\"]}]}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"4ab1ed61-2930-46d4-af6f-778279d7414a\\\"}],\\\"filters\\\": [{\\\"column\\\": [\\\"region\\\"],\\\"oper\\\": \\\"in\\\",\\\"values\\\": [\\\"Midwest\\\"],\\\"is_mandatory\\\": false,\\\"is_single_value\\\": false,\\\"display_name\\\": \\\"region\\\"}],\\\"layout\\\": {\\\"tabs\\\": [{\\\"name\\\": \\\"Tab 1\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_1\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_4\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"2c4014b5-a606-4639-8ad0-01032ff3fc13\\\"},{\\\"name\\\": \\\"Tab 2\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_2\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_3\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"185b4875-e7c5-43d2-a9bc-0a404107a3ec\\\"}]}}}\", \"info\": { \"filename\": \"Copy of Total Sales.liveboard.tml\", \"name\": \"Copy of Total Sales\", \"id\": \"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\", \"type\": \"liveboard\", \"status\": { \"status_code\": \"OK\" } }" + ], + "create_new": true, + "all_orgs_context": false, +}' +---- + +==== Example response + +If the API request is successful, ThoughtSpot schedules an import task, and returns the task name and ID in the API response: + +[source,JSON] +---- +{ + "tenant_id": "default-tenant-id", + "org_id": 0, + "task_id": "075c322f-b000-4776-9c44-89e13420980c", + "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", + "import_response": null, + "task_status": "IN_QUEUE", + "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "import_policy": "PARTIAL_OBJECT", + "created_at": null, + "in_progress_at": null, + "completed_at": null, + "total_object_count": 2, + "object_processed_count": null, + "modified_at": null, + "author_display_name": "UserA" +} +---- + +===== Response codes + +[options="header", cols="1,4"] +|==== +|HTTP status code|Description +|**200**|Async TML Import Task submitted successfully +|**400**|Invalid request +|**401**|Unauthorized access +|**403**|Forbidden access +|**500**|Unexpected Error |==== -=== Check import task status +=== Fetch status of the TML import task -After you schedule an import task, you can check the status of the import task using the `POST /api/rest/2.0/metadata/tml/async/status` API endpoint. +To fetch the status of a scheduled import task, send a `POST` request to the `POST /api/rest/2.0/metadata/tml/async/status` API endpoint. + +In the request body, include the following attributes: [width="100%" cols="2,4,1"] [options='header'] |==== |Form parameter|Description| Default -|`task_ids` |__Array of strings__. Array of task IDs to fetch status for. |__None__ +|`task_ids` |__Array of strings__. Task IDs assigned to the scheduled TML async import operations. | __None__ +| `task_status` | __Array of strings__. Status of the scheduled import tasks to filter on. The following options are available: + + +* `COMPLETED` + +* `IN_QUEUE` + +* `IN_PROGRESS` + +* `FAILED` +| __None__ +|`author_identifier` + +__Optional__ |__String__. GUID of the author who initiated the import request. | __None__ +|`include_import_response` + +__Optional__ |__Boolean__. Specify whether to include import response in the task status objects.| `false` +|`record_offset` + +__Optional__ |__Integer__. The offset point, starting from where the task status should +be included in the response. | `0` +|`record_size` + +__Optional__ a|__Integer__. The number of task statuses to include in the +response starting from offset position. + +[NOTE] +==== +The maximum limit for the `record_size` that user can pass in an API request is 50. If the `record_size` exceeds this threshold, the API returns a bad request error. To extend the `record_size` limit, contact ThoughtSpot Support. +==== +| `5` +|`include_import_response`|__Boolean__. Specify whether to include the import response when fetching status for the import task. + |==== -The API response includes the task status and the import results for each task. +[IMPORTANT] +==== +You can poll up to 100 API requests per minute to get details of your TML import tasks. The API returns an error if you exceed this rate limit. +==== -== Export TML +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/status' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "record_offset": 0, + "record_size": 5, + "include_import_response": true, + "task_ids": [ + "c8c8c4da-0bc8-4460-8039-cfa7fd598335" + ], + "task_status": [ + "COMPLETED" + ], + "author_identifier": "95ac814f-eb01-4625-93c7-c7624b29d226" +}' +---- -To export a TML object from ThoughtSpot, use one of the following API endpoints: +==== Example response -* +++POST /api/rest/2.0/metadata/tml/export+++ (REST API v2) -* xref:tml-api.adoc#export[POST /tspublic/v1/metadata/tml/export] (REST API v1) +If the API request is successful, ThoughtSpot returns the status details of the TML async import tasks. +If Orgs are enabled on your instance, the API returns task status only for objects within the current Org context. -You can export TML objects with FQNs by setting the `export_fqn` parameter to `true` in the API request. The exported TML file includes the FQN for each referenced object. This is useful when importing TML files to a different ThoughtSpot environment, as it allows ThoughtSpot to uniquely identify referenced objects. +[source,JSON] +---- +{ + "status_list": [ + { + "tenant_id": "default-tenant-id", + "org_id": 0, + "task_id": "c8c8c4da-0bc8-4460-8039-cfa7fd598335", + "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", + "import_response": { + "object": [ + { + "filename": "tml_0", + "zip_filename": "zip_tml_0", + "response": { + "status": { + "status_code": "ERROR", + "error_message": "Invalid YAML/JSON syntax in file." + } + }, + "request_index": 0 + }, + { + "filename": "tml_1", + "zip_filename": "zip_tml_1", + "response": { + "status": { + "status_code": "ERROR", + "error_message": "Invalid YAML/JSON syntax in file." + } + }, + "request_index": 1 + } + ], + "status": { + "status_code": "OK", + "error_code": 0, + "error_message": "" + } + }, + "task_status": "COMPLETED", + "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "import_policy": "PARTIAL_OBJECT", + "created_at": 1732601184212, + "in_progress_at": 1732601184255, + "completed_at": 1732601184476, + "total_object_count": 2, + "object_processed_count": 2, + "modified_at": 1732601184476, + "author_display_name": "UserA" + } + ], + "last_batch": true +} +---- -You can also export TML for multiple objects at the same time by passing multiple GUIDs in the `metadata` array. For example, you can export a Liveboard along with all its dependent Answers and Models in one API call. +===== Response codes -[NOTE] -==== -ThoughtSpot does not export TML for the following object types: Embrace connections, ThoughtSpot-managed tables and schema, Spot IQ generated objects, and user-uploaded data objects. -==== +[options="header", cols="1,4"] +|==== +|HTTP status code|Description +|**200**|Async TML import task status fetched successfully +|**400**|Invalid request +|**401**|Unauthorized access +|**403**|Forbidden access +|**500**|Unexpected Error +|==== + +== Export a TML +To export the TML data, your account must have the `DATAMANAGEMENT` (Can manage data) or `ADMINISTRATION` (Can administer ThoughtSpot) privilege. + +The default format to export the objects is YAML is v1, and JSON in v2 APIs. To export the TML representation of the metadata objects from ThoughtSpot in JSON or YAML format, use one of the following endpoints: + +* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml[**POST** /api/rest/2.0/metadata/tml/export] (REST API v2) +* xref:tml-api.adoc#export[**POST** /tspublic/v1/metadata/tml/export] (REST API v1) + +To export the TML representation of the metadata objects in a *batch*, use one of the following endpoints: + +* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml-batched[**POST** /api/rest/2.0/metadata/tml/export/batch] (REST API v2) +* xref:tml-api.adoc#BatchExport[**POST** /tspublic/v1/metadata/tml/export/batch] (REST API v1) + +There are several export options available with these APIs: + +=== Metadata specification for Answers +To export a specific metadata object, specify the name or ID of the object. + +For Answer objects, the `identifier` is optional, and you can define parameters such as `session_identifier` and `generation_number` instead. These attributes can be used to export unsaved Answers generated from Spotter queries or Answers that do not have the name and ID assigned. + +=== Export associated objects + +To export associated objects, set the following attributes: + +* `export_associated` + +When set to `true`, exports the associated objects for the `export_ids` specified in the API request. The API exports any underlying Models, tables, or views for a given object. By default, the API does not export these underlying objects. +* `export_dependent` + +Specifies if the Tables of the referenced Connection object must be included in the export. +* `export_connection_as_dependent` + +Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. + +=== Export FQNs + +When `export_fqn=true`, the API exports the FQNs of the referenced objects in the TML data. For example, if you are exporting a Liveboard and its associated objects, the API returns the Liveboard TML data with the FQNs of the referenced Model. +Note that the FQN of a referenced object is the same as the GUID of that object. + +ThoughtSpot recommends adding the fqn property before importing the TML objects into the system, because only the name of a referenced object is not sufficient to identify the referenced object during TML import. For example, if your ThoughtSpot instance has two Models with the same name, the TML import for a Liveboard that uses one of these Models would fail unless the Liveboard TML includes the FQN of the referenced object. +The `export_fqn` attribute is useful when ThoughtSpot has multiple objects with the same name and you want to eliminate ambiguity during TML import. The `export_fqn=true` property adds the FQNs of the referenced objects in the TML export API response and saves the manual effort of adding FQNs for TML import. + +=== Export schema + +Specifies the schema version to use during TML export. For link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank], set `export_schema_version` to v2. +The v1 schema is used for Worksheet objects (Deprecated). + +=== Additional export options for REST API v2 +Following are some additional attributes which can be set for exporting objects: + +* `include_obj_id_ref` + +When set to `true`, exports the object ID of the referenced object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. + +* `include_guid` + +When set to `true`, exports the guid of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. +* `include_obj_id` + +When set to `true`, exports the object ID of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. +* `export_with_associated_feedbacks` + +When set to `true`, exports the TML of an object along with all feedback, such as Spotter or Sage feedback, associated with that object. No feedback file will be exported if there are no feedback entries associated with the object +* `export_column_security_rules` [beta betaBackground]^Beta^ + +When set to `true`, exports the column-level security rules defined on the object. Contact ThoughtSpot Support to enable the feature. +* `export_with_column_aliases` [beta betaBackground]^Beta^ + +When set to `true`, export column aliases of the Model if the data Model includes any link:https://docs.thoughtspot.com/cloud/latest/column-aliases[column aliases, window=_blank]. + +=== Export in a batch +This API operation supports exporting User, User Group, and Role objects only. +To export objects in a batch, set the following additional attributes: + +* `batch_size` + +Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation. + +* `batch_offset` + +Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API. + +For more information, see the API documentation in REST API v2 Playground and xref:tml-api.adoc[Export a TML object using REST API v1]. + + +== TML modification + +ThoughtSpot offers a lot of flexibility within its set of xref:intro-thoughtspot-objects.adoc[data objects], and there is no particular hierarchy to TML files, but rather just some rules. Visit this page for detailed information on xref:modify-tml.adoc[TML modification]. + +== Limitations of working with TML files +There are certain limitations to the changes you can apply by editing a ThoughtSpot object through TML. Visit link:https://docs.thoughtspot.com/cloud/latest/tml#_limitations_of_working_with_tml_files[Limitations of working with TML files, window=_blank] for detailed information. + +[#yamlReimport] +=== YAML reimport in REST API v2 Playground +If you are using the REST API Playground to import TML in YAML format, note that copying YAML content directly in the input field will likely result in the `Invalid YAML/JSON syntax in file` error. +When you copy the YAML output from the export TML API response in the Playground, the copied content is wrapped in quotation marks and include escaped newline characters (`\n`). When you paste this content directly in the `metadata_tml` input field, the API Playground double-escapes characters or removes necessary newline (`\n`) characters. Due to improper formatting, the YAML input becomes invalid for import, resulting in the `Invalid YAML/JSON syntax in file` error. + +To work around this issue, follow these steps: + +. After you +++export TML+++ in the Playground, use the `copy to clipboard` option to copy the YAML output from the API response as shown in this video. + ++ + +[div videoContainer] +-- +video::./images/tml-export.mp4[width=100%,options="autoplay,loop"] +-- ++ +The output copied from the API response is enclosed in quotation marks (`"`). +For example, `"guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n"`. +. Paste the YAML output copied from the export TML API response into a text editor. +. Remove the quotation marks, update the TML, and ensure that the YAML is properly formatted: + +`guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n` +. When +++importing TML in the Playground+++, do not paste the YAML directly into the `metadata_tmls` input field. Instead, use the JSON editor to add the YAML. +. To open the JSON editor, click *View JSON*. + +In the JSON preview, you'll see the following code: ++ +[source,JSON] +---- +{ + "metadata_tmls": [ + "metadata_tmls3", + "metadata_tmls5", + ], + "import_policy": "PARTIAL", + "create_new": false, + "all_orgs_context": false +} +---- +. Remove the text in the `metadata_tmls` array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the otehr TML. ++ +[source,JSON] +---- +{ + "metadata_tmls": [ + "guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n" + ], + "import_policy": "PARTIAL", + "create_new": false, + "all_orgs_context": false +} +---- ++ +You may see double-escaped characters in JSON preview. For example, `\\n` instead `\n`. However, these will not be imported in the actual payload. +. To submit the request, click **Try it Out**. + ++ +In the following video, you can see that pasting YAML directly in the `metadata_tmls` form field results in an error due to additional quotation marks and improper formatting. Using the JSON editor, you can paste the YAML inside the array and import TML successfully. ++ + +[div videoContainer] +-- +video::./images/import-tml.mp4[width=100%,options="autoplay,loop"] +-- + +== Deployment and version control of TML objects +For information about version control and TML deployment, see the following pages: -== Validate TML +* xref:version_control.adoc[Git integration and version control] +* xref:development-and-deployment.adoc[TML files from development to testing and production environments] -Before importing TML objects, you can validate TML by setting the `import_policy` to `VALIDATE_ONLY` in the import API request. The API response includes details about validation errors for each TML object. +//// +When embedding or deploying a third-party application in their environments, most organizations use defined practices at various stages of their SDLC process. Users typically use a version control system and CI-CD pipeline to push their . -== Modify TML +ThoughtSpot instances act as a constantly running service, so deployment only involves publishing ThoughtSpot content, in the form of ThoughtSpot Modeling Language (TML) files to a given ThoughtSpot instance. The three traditional steps to building an SDLC process with ThoughtSpot are: -For information about TML modification best practices and recommendations, see xref:modify-tml.adoc[TML modification]. +* Exporting TML objects into a source control system (Git, etc.) +* Altering copies of the TML files for the next stage/environment +* Importing the TML files into the new environment -== Related resources +But this changed with the link:https://developers.thoughtspot.com/docs/git-integration[Git integration] feature. ThoughtSpot now allows you to connect your deployment instance to a Git repository, push TML files to CI/CD pipelines, and deploy commits from your Git repository to your production environment. +However, ThoughtSpot’s Git integration does not support moving objects within the same Org or application instance. For example, it does not support moving objects in an environment where xref:multitenancy-without-orgs[multi-tenancy is implemented using groups]. +/// -* link:https://docs.thoughtspot.com/cloud/latest/tml[TML reference, window=_blank] -* xref:modify-tml.adoc[TML modification] -* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] From 41761aafb7c147402f58fe47791dd08709e1912b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:21 +0530 Subject: [PATCH 21/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to embed-spotterViz.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] --- modules/ROOT/pages/embed-spotterViz.adoc | 378 ++++++++++++++++++----- 1 file changed, 305 insertions(+), 73 deletions(-) diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index cf932f912..88bd82873 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -45,11 +45,11 @@ For SpotterViz panel customization, pass the `spotterViz` configuration object w Brand name:: To replace the default **SpotterViz** label with your product or assistant name, specify the brand name string in `brandName`. -Greeting headline:: Customize the greeting prefix displayed before the brand name using `brandHeadline`. For example, setting `brandHeadline: \"Hi there! I'm\"` combined with `brandName: \"Dashboard Builder\"` renders as \"Hi there! I'm Dashboard Builder\". +Greeting headline:: Customize the greeting prefix displayed before the brand name using `brandHeadline`. For example, setting `brandHeadline: "Hi there! I'm"` combined with `brandName: "Dashboard Builder"` renders as "Hi there! I'm Dashboard Builder". Description:: Use `description` to include your custom description text below the greeting. This helps users understand what the AI assistant can do. -Input placeholder:: Use `inputChatPlaceholder` to customize the placeholder text shown in the chat input box when it is empty. By default, this text is displayed as \"Let me help you build this Liveboard\". +Input placeholder:: Use `inputChatPlaceholder` to customize the placeholder text shown in the chat input box when it is empty. By default, this text is displayed as "Let me help you build this Liveboard". Starter prompts:: SpotterViz displays the question suggestions in the panel to help users begin an AI-assisted analysis. Each prompt has a short display label (`displayText`) and a full prompt string (`fullPrompt`) sent to Spotter when clicked. @@ -67,31 +67,6 @@ The SpotterViz panel displays the restore button on checkpoint cards and thumbs- * `Action.SpotterVizCheckpointRestore` * `Action.SpotterVizFeedback` -[#spotter-viz-loader] -=== Customize the loading state [.version-badge.new]#New in SDK 1.51.0 | 26.8.0.cl# - -// SOURCE: src/embed/spotter-viz-utils.ts @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl -// SOURCE: SCAL-309017 -When SpotterViz is generating a response, ThoughtSpot displays a default loading headline and rotating tips. You can replace these with custom text using the `loaderHeadline` and `loaderTips` properties in `SpotterVizConfig`. - -[width="100%", cols="2,1,4"] -[options="header"] -|==== -|Property |Type |Description -|`loaderHeadline` |`string` |Custom headline text displayed during the SpotterViz loading state. Replaces the default loading headline shown while Spotter is processing a response. -|`loaderTips` |`SpotterVizLoaderTip[]` |Array of tip objects shown in rotation during the loading state. Each tip object requires a `label` (string) and `text` (string). -|==== - -The `SpotterVizLoaderTip` interface: - -[source,TypeScript] ----- -interface SpotterVizLoaderTip { - label: string; // Short label rendered before the tip text (for example, "Tip" or "Did you know") - text: string; // Tip body text shown to the user during loading -} ----- - === SpotterViz in Liveboard embedding [source,javascript] ---- @@ -127,13 +102,6 @@ const embed = new LiveboardEmbed('#embed-container', { fullPrompt: 'Show me revenue broken down by region.', }, ], - // Requires Visual Embed SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl - loaderHeadline: 'Crunching the numbers...', - loaderTips: [ - { label: 'Tip', text: 'Try asking about revenue by region' }, - { label: 'Tip', text: 'Use natural language — no SQL needed' }, - { label: 'Tip', text: 'Ask for comparisons, trends, and breakdowns' }, - ], }, hideActions: [Action.SpotterVizCheckpointRestore], }); @@ -163,11 +131,6 @@ const embed = new AppEmbed('#embed-container', { brandName: 'Dashboard Builder', description: 'Explore your data with AI.', hideStarterPrompts: true, - // Requires Visual Embed SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl - loaderHeadline: 'Thinking...', - loaderTips: [ - { label: 'Did you know', text: 'You can ask follow-up questions in the same session' }, - ], }, hideActions: [Action.SpotterVizCheckpointRestore] }); @@ -175,21 +138,6 @@ const embed = new AppEmbed('#embed-container', { embed.render(); ---- -[#insight-tiles] -== SpotterViz Insight Tiles [earlyAccess eaBackground]#Early Access# [.version-badge.new]#New in 26.8.0.cl# - -// SOURCE: SCAL-309017 -// TODO: [WRITER] Confirm whether Insight Tiles are GA or Early Access in 26.8.0.cl. Update badge accordingly. -// TODO: [WRITER] Add a screenshot of Insight Tiles in the Liveboard agent panel once available. -// TODO: [WRITER] Confirm with the SpotterViz team what SDK configuration, if any, is needed to enable or control Insight Tiles in embedded view. If there are new SDK properties or Action IDs for Insight Tiles, add them here. -// TODO: [WRITER] Confirm whether Insight Tiles require any new privileges or feature flags on the ThoughtSpot instance. - -SpotterViz Insight Tiles provide non-interactive AI-generated data summaries directly within the Liveboard agent panel. When Spotter generates a response, Insight Tiles surface key findings as digestible cards inside the SpotterViz panel, allowing your users to consume AI-generated insights without navigating away from the Liveboard. - -Insight Tiles are displayed automatically when the SpotterViz panel is enabled and the Liveboard agent is active. No additional SDK configuration is required to enable this feature. - -// TODO: [WRITER] If there are `disabledActions` or `hiddenActions` entries for Insight Tiles, add them here with the correct Action enum values. Verify with the SDK team. - == Customizing the style and appearance You can customize the visual appearance of the SpotterViz panel using the CSS customization framework in the SDK. Use any of the following CSS variables in the `customizations` object of the `init()` call to customize the panel style and appearance. @@ -225,40 +173,324 @@ thinking step connector lines and dots. | CSS variable | Description | `--ts-var-spotterviz-text-primary` -| Primary text color in the SpotterViz panel. Applies to user-entered prompt text and AI response text. +| Primary text color in the SpotterViz panel. Applied to the SpotterViz panel header, close icon, user message text, agent response text, thinking step headers, checkpoint "Liveboard updated" text, brand name and description, text in the empty state, starter prompt text, and upvote/downvote icons. | `--ts-var-spotterviz-text-secondary` -| Secondary text color. Applies to timestamps, helper text, and de-emphasized labels. +| Secondary text color in the SpotterViz panel. Applied to checkpoint version labels ("version N"), tool call display, and the copy action color on input/JSON/output panels. -| `--ts-var-spotterviz-text-accent` -| Accent text color. Applies to suggestion chip labels and interactive link text. +| `--ts-var-spotterviz-emptystate-spotterviz-color` +| Text color of the SpotterViz brand label shown in the empty state, displayed below the SpotterViz icon. |=== -=== Input and interactive elements +=== Chat input [cols="3,3", options="header"] |=== | CSS variable | Description | `--ts-var-spotterviz-input-background` -| Background color of the chat input area. +| Background color of the chat input field. + +| `--ts-var-spotterviz-input-placeholder-color` +| Placeholder text color in the chat input field. + +| `--ts-var-spotterviz-input-cta-color` +| Color of the submit (CTA) button in the chat input field. + +| `--ts-var-spotterviz-input-cta-hover-color` +| Hover color of the submit (CTA) button in the chat input field. + +| `--ts-var-spotterviz-reference-icon-hover-background` +| Background color of the reference-mode toggle button in the chat input when it is in the unselected state and the user hovers over it. + +| `--ts-var-spotterviz-reference-icon-selected-color` +| Icon color for the reference-mode selected state. Applies to the toggle button when active and to the icon badge on referenced entity chips in the chat input. + +| `--ts-var-spotterviz-reference-icon-selected-background` +| Background color for the reference-mode selected state. Applies to the reference-mode toggle button when active and to the icon badge on referenced entity chips in the chat input. +|=== + +=== Starter prompts + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-prompt-card-background` +| Background color of the starter prompt suggestion cards. + +| `--ts-var-spotterviz-prompt-card-hover-background` +| Background color of starter prompt suggestion cards on hover. + +|=== + +=== User messages +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-message-background` +| Background color of the user's chat message bubbles. + +| `--ts-var-spotterviz-usermessage-icon-hover` +| Hover color of the expand button on user chat message bubbles. + +| `--ts-var-spotterviz-usermessage-icon-background` +| Background color of the expand button on user chat message bubbles. + +|=== + +=== Thinking and progress states + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-thinking-inprogress-header-color` +| Color of the thinking step header text while the agent is still working. + +| `--ts-var-spotterviz-thinking-completed-header-color` +| Color of the thinking step header text once the step is complete. Also +applied to the arrow icon on the "work done" state. + +| `--ts-var-spotterviz-thinking-work-done-icon-color` +| Color of the final completion indicator icon (the green circle) shown +when all agent work is done. + +| `--ts-var-spotterviz-thinking-cta-hover-background` +| Hover background color for the working/work done CTA element. +|=== + +=== Tool calls + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-tool-call-background` +| Background color of tool call panels. + +| `--ts-var-spotterviz-tool-title-color` +| Color of tool titles and icons inside tool call panels. + +| `--ts-var-spotterviz-tool-border-color` +| Border color of tool call panels. + +| `--ts-var-spotterviz-tool-json-input-background` +| Background color of the JSON input/output panel inside a tool call. + +| `--ts-var-spotterviz-tool-json-input-color` +| Text color of the JSON input/output panel inside a tool call. -| `--ts-var-spotterviz-input-text-color` -| Text color inside the chat input box. +| `--ts-var-spotterviz-tool-feedback-button-background` +| Background color of the upvote/downvote feedback buttons. -| `--ts-var-spotterviz-send-button-color` -| Color of the send button icon. +| `--ts-var-spotterviz-tool-feedback-button-hover` +| Hover background color of the upvote/downvote feedback buttons. -| `--ts-var-spotterviz-suggestion-chip-background` -| Background color of starter prompt suggestion chips. +|=== + +=== Checkpoints + +[cols="3,3", options="header"] +|=== +| CSS variable | Description +| `--ts-var-spotterviz-last-checkpoint-background` +| Background color of the last checkpoint summary section. +| `--ts-var-spotterviz-last-checkpoint-border` +| Border color of the last checkpoint summary section. +|=== + +=== Liveboard edit toolbar + +The Liveboard edit toolbar hosts the SpotterViz trigger button and other Liveboard editing controls. You can customize it independently from the SpotterViz panel itself. + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-liveboard-edit-toolbar-border` +| Border color of the Liveboard edit header toolbar. + +| `--ts-var-liveboard-edit-toolbar-selected-background` +| Background color of the selected (active) section in the Liveboard edit header toolbar. + +| `--ts-var-liveboard-edit-toolbar-selected-text-color` +| Text color of the selected section in the Liveboard edit header toolbar. Also applied to the Add button and toolbar icons in the selected state. + +| `--ts-var-liveboard-edit-toolbar-text` +| Text color of unselected items in the Liveboard edit header toolbar. Also applied to the Add button and toolbar icons in the unselected state. + +| `--ts-var-liveboard-edit-toolbar-hover-background` +| Hover background color of unselected items in the Liveboard edit header +toolbar. Also applied to the Add button and toolbar icons on hover. + +| `--ts-var-liveboard-edit-toolbar-hover-text-color` +| Hover text color of unselected items in the Liveboard edit header toolbar. -| `--ts-var-spotterviz-suggestion-chip-text-color` -| Text color inside starter prompt suggestion chips. |=== -== Related resources +=== Apply CSS variable customizations + +Pass CSS variables using the `customCSSVariables` map inside the +`customizations.style` object of the `init()` call. + +[source,javascript] +---- +import { + LiveboardEmbed, + AuthType, + init, +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/ts-token').then(r => r.json()).then(d => d.token), + customizations: { + style: { + customCSSVariables: { + // Panel and layout + '--ts-var-spotterviz-panel-background': '#1a1a2e', + '--ts-var-spotterviz-border-color': '#3a3a5c', + '--ts-var-spotterviz-footer-text-color': '#a0a0c0', + + // Text colors + '--ts-var-spotterviz-text-primary': '#ffffff', + '--ts-var-spotterviz-text-secondary': '#a0a0c0', + '--ts-var-spotterviz-emptystate-spotterviz-color': '#8080b0', + + // Chat input + '--ts-var-spotterviz-input-background': '#16213e', + '--ts-var-spotterviz-input-placeholder-color': '#606080', + '--ts-var-spotterviz-input-cta-color': '#6c63ff', + '--ts-var-spotterviz-input-cta-hover-color': '#8a84ff', + + // Starter prompts + '--ts-var-spotterviz-prompt-card-background': '#0f3460', + '--ts-var-spotterviz-prompt-card-hover-background': '#1a4a7a', + + // User messages + '--ts-var-spotterviz-message-background': '#0f3460', + + // Thinking / progress states + '--ts-var-spotterviz-thinking-inprogress-header-color': '#a0a0ff', + '--ts-var-spotterviz-thinking-completed-header-color': '#4caf50', + '--ts-var-spotterviz-thinking-work-done-icon-color': '#4caf50', + '--ts-var-spotterviz-thinking-cta-hover-background': '#2a2a4e', + + // Tool calls + '--ts-var-spotterviz-tool-call-background': '#12122a', + '--ts-var-spotterviz-tool-title-color': '#c0c0ff', + '--ts-var-spotterviz-tool-border-color': '#3a3a5c', + '--ts-var-spotterviz-tool-json-input-background': '#0d0d1a', + '--ts-var-spotterviz-tool-json-input-color': '#c0ffc0', + '--ts-var-spotterviz-tool-feedback-button-background': '#2a2a4e', + '--ts-var-spotterviz-tool-feedback-button-hover': '#3a3a6e', + + // Checkpoints + '--ts-var-spotterviz-last-checkpoint-background': '#1a2a3e', + '--ts-var-spotterviz-last-checkpoint-border': '#3a5a7c', + + // Liveboard edit toolbar + '--ts-var-liveboard-edit-toolbar-border': '#3a3a5c', + '--ts-var-liveboard-edit-toolbar-selected-background': '#6c63ff', + '--ts-var-liveboard-edit-toolbar-selected-text-color': '#ffffff', + '--ts-var-liveboard-edit-toolbar-text': '#a0a0c0', + '--ts-var-liveboard-edit-toolbar-hover-background': '#2a2a4e', + '--ts-var-liveboard-edit-toolbar-hover-text-color': '#ffffff', + }, + }, + }, +}); +---- + +=== SpotterViz button customization +The SpotterViz trigger button renders in the Liveboard edit toolbar. You can customize it in two ways: + +Button icon:: +The SpotterViz button uses the `rd-icon-spotter-viz` icon from the icon sprite. To replace it with a custom icon, set the `iconSpriteUrl` property in your `customizations` object pointing to a sprite that includes the `rd-icon-spotter-viz` icon ID. +For more information, see xref:customize-icons.adoc[Customize icons]. + +Button text:: +The button label follows the `brandName` value you set in the `spotterViz` configuration object. Setting `brandName` in your embed configuration automatically updates the button text to match, keeping your custom brand name consistent across the panel and the toolbar button. + +Button colors:: +Use the `--ts-var-liveboard-edit-toolbar-*` variables described in the <<_liveboard_edit_toolbar,Liveboard edit toolbar>> table above to control the button's background, text, and hover colors in both the selected and unselected states. + +== Customizing app interactions +The following embed events are emitted by the SpotterViz panel. + +* `EmbedEvent.SpotterVizCheckpointCreated` + +Emitted when a checkpoint is created in the SpotterViz panel. +* `EmbedEvent.SpotterVizCheckpointRestored` + +Emitted when a checkpoint is restored in the SpotterViz panel. +* `EmbedEvent.SpotterVizClosed` + +Emitted when the SpotterViz panel is closed. +* `EmbedEvent.SpotterVizError` + +Emitted when an error occurs in the SpotterViz panel. +* `EmbedEvent.SpotterVizInit` + +Emitted when the SpotterViz panel mounts in embed mode. +* `EmbedEvent.SpotterVizQueryTriggered` + +Emitted when the user submits a prompt in the SpotterViz panel. +* `EmbedEvent.SpotterVizResponseComplete` + +Emitted when the SpotterViz response ends. + +[source,javascript] +---- +liveboardEmbed.on(EmbedEvent.SpotterVizInit, (payload) => { + console.log('SpotterViz initialized', payload); + // payload: { liveboardId: string } +}); + +liveboardEmbed.on(EmbedEvent.SpotterVizError, (payload) => { + console.log('SpotterViz error', payload); +}); + +liveboardEmbed.on(EmbedEvent.SpotterVizQueryTriggered, (payload) => { + console.log('SpotterViz query triggered', payload); + // payload: { query: string, sessionId: string } +}); + +liveboardEmbed.on(EmbedEvent.SpotterVizResponseComplete, (payload) => { + console.log('SpotterViz response complete', payload); + // payload: { sessionId: string, messageId: string } +}); +---- + +The following host events programmatically trigger workflows in embedded view: + +* `HostEvent.InitSpotterVizConversation` + +Initializes a new SpotterViz conversation. +* `HostEvent.SpotterVizSendUserMessage` + +Sends a prompt to the SpotterViz panel. +* `HostEvent.OpenSpotterVizPanel` + +Opens the SpotterViz panel. +* `HostEvent.CloseSpotterVizPanel` + +Closes the SpotterViz panel. + +[source,javascript] +---- +liveboardEmbed.trigger(HostEvent.InitSpotterVizConversation); +liveboardEmbed.trigger(HostEvent.SpotterVizSendUserMessage, { + query: 'Show me revenue by region', +}); +---- + +//// +[#runtime-filters] +== Runtime filters and insight tiles +Runtime filters and parameters passed to `LiveboardEmbed` are in SpotterViz-generated insight tiles. When a runtime filter is applied, Spotter automatically regenerates the tile's insights using the filtered data context. + +No additional configuration is required. Runtime filters specified via `runtimeFilters` in `LiveboardViewConfig` are automatically applied to all Insight Tiles on the same Liveboard. +//// + +== Additional resources + +See the following documentation for additional information about embedding Liveboards and customizing Liveboard experience: -// TODO: [WRITER] Update link once the product docs SpotterViz page is confirmed for 26.8.0.cl. -* link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz in ThoughtSpot, window=_blank] -* xref:whats-new.adoc[What's New] -* xref:api-changelog.adoc[Visual Embed SDK changelog] +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:full-embed.adoc[Embed full ThoughtSpot experience] +* xref:embed-events.adoc[Embed events reference] +* xref:events-hostEvents.adoc[Host events reference] +* xref:SpotterVizConfig.adoc[SpotterVizConfig interface] From b66aeef5fc5c98f6821e850d826a6931ee798bcc Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:23 +0530 Subject: [PATCH 22/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to api-changelog.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] From e5cd40be37cebbdf0c698cc4c904f5a77fbd9e94 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:25 +0530 Subject: [PATCH 23/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to rest-apiv2-changelog.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] From d646873f27d6b942e8ba0249aa379693387284e5 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:26 +0530 Subject: [PATCH 24/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to embed-spotter.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] From 5f0a9577278c53a56ca4bb9771eab9c3c87f805c Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:27 +0530 Subject: [PATCH 25/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to full-app-customize.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] From eb7a8f885c06899e1701297e28a080c41acd5f9e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:29 +0530 Subject: [PATCH 26/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to security-settings.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] From 4bac53c8c607f737d5b1dde07f69c82197431f01 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:30 +0530 Subject: [PATCH 27/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to tml.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] From 38c9dfe5bad1c2191f5270cab6b2f499871693a7 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:20:31 +0530 Subject: [PATCH 28/63] fix: restore full content + add 26.8.0.cl/SDK 1.51.0 updates to embed-spotterViz.adoc [SCAL-299746 SCAL-312622 SCAL-309017 SCAL-307283 SCAL-317357 SCAL-312731 SCAL-320438] From f2c56fadada7b47ee3ce3278303ba9a8873553b4 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 09:18:07 +0530 Subject: [PATCH 29/63] docs(embed-spotter): add 26.8.0.cl / SDK 1.51.0 Spotter Analysts, onboarding, and Action updates (SCAL-310399, SCAL-312622, SCAL-293483, SCAL-314448, SCAL-299746) --- modules/ROOT/pages/embed-spotter.adoc | 208 +++++++++++++++++++++++++- 1 file changed, 206 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index eaaf2b1a0..30080e97d 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -8,6 +8,205 @@ 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. +// SOURCE: SCAL-310399, SCAL-312622, SCAL-293483, SCAL-314448, SCAL-299746 +// ============================================================ +// NEW IN 26.8.0.cl / SDK 1.51.0 — WRITER REVIEW REQUIRED +// ============================================================ +// The following sections document new features shipping in ThoughtSpot Cloud 26.8.0.cl +// and Visual Embed SDK 1.51.0. Review all TODO comments before publishing. +// ============================================================ + +[#whats-new-26-8] +== What's new in 26.8.0.cl (SDK 1.51.0) + +// SOURCE: SCAL-310399, SCAL-312622 +=== [EA] Spotter Analysts + +// TODO: [WRITER] Confirm EA vs GA status for Analysts with Karamveer Singh / Agents Experience team (SCAL-310399). +// TODO: [WRITER] Verify these exact Action enum values exist in the published SDK 1.51.0 types.ts: +// Action.CreateAnalyst, Action.EditAnalyst, Action.CopyAnalyst, Action.ShareAnalyst, Action.DeleteAnalyst +// Check: https://github.com/thoughtspot/visual-embed-sdk/blob/main/src/types.ts +// TODO: [WRITER] Confirm whether showAnalysts defaults to false in TSE embed (Analysts disabled by default per SCAL-312622). +// TODO: [WRITER] Verify that spotterAnalystLabel and spotterAnalystsLabel are the confirmed property names +// in SpotterEmbedViewConfig. Source: src/embed/conversation.ts @version SDK: 1.51.0 + +ThoughtSpot Cloud 26.8.0.cl introduces *Spotter Analysts* [.version-badge.new]#New# — a feature that allows users to create and manage AI agents (Analysts) directly within the Spotter interface. Each Analyst is scoped to a data model and can be configured with custom instructions, personas, and conversation starters. + +In embedded applications, Analysts are *disabled by default*. You can enable and customize the Analysts experience using the configuration options described in this section. + +==== Enable the Analysts panel + +To show the Analysts panel in the embedded Spotter interface, set `showAnalysts` to `true` in `SpotterEmbedViewConfig`: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + // Enable the Analysts panel (disabled by default in embedded mode) + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + showAnalysts: true, +}); +spotterEmbed.render(); +---- + +==== Embed a single Analyst + +// TODO: [WRITER] Confirm the exact property name for embedding a single Analyst by GUID. +// Verify with the SDK team whether it is 'analystId', 'defaultAnalystId', or another name. +To embed a single, pre-selected Analyst, pass the Analyst GUID in the embed configuration: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + showAnalysts: true, + // TODO: [WRITER] Replace with confirmed property name for single-Analyst embed. + // analystId: '<%=analystGUID%>', +}); +spotterEmbed.render(); +---- + +==== Disable Analyst actions + +Use `disabledActions`, `hiddenActions`, or `visibleActions` arrays to control which Analyst-related menu actions are available to users. The following action IDs apply to Analysts: + +// TODO: [WRITER] Verify ALL of these action names in the published types.ts for SDK 1.51.0. +// Source: https://github.com/thoughtspot/visual-embed-sdk/blob/main/src/types.ts + +[width="100%",cols="2,3"] +[options="header"] +|==== +|Action ID |Description +|`Action.CreateAnalyst` |Create a new Analyst +|`Action.EditAnalyst` |Edit an existing Analyst +|`Action.CopyAnalyst` |Duplicate an Analyst +|`Action.ShareAnalyst` |Share an Analyst with other users +|`Action.DeleteAnalyst` |Delete an Analyst +|==== + +Example — hide Create and Delete Analyst actions: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + showAnalysts: true, + // Hide specific Analyst menu actions from all users + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + hiddenActions: [ + Action.CreateAnalyst, + Action.DeleteAnalyst, + ], +}); +spotterEmbed.render(); +---- + +==== Customize Analysts label strings + +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl (SCAL-312622) +Use `spotterAnalystLabel` and `spotterAnalystsLabel` to replace the default "Analyst" / "Analysts" label text in the Spotter interface with custom terminology suited to your application: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + showAnalysts: true, + // Custom label for a single Analyst (default: "Analyst") + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + spotterAnalystLabel: 'Assistant', + // Custom label for the Analysts section heading (default: "Analysts") + spotterAnalystsLabel: 'Assistants', +}); +spotterEmbed.render(); +---- + +// SOURCE: SCAL-293483, SCAL-314448 +=== Spotter onboarding starter prompts + +// TODO: [WRITER] Confirm exact EA/GA status for Spotter onboarding with the Agents Experience team (SCAL-293483). +// TODO: [WRITER] Verify that enableStarterPrompts is the correct property name and that the default is false. +// Source: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl + +ThoughtSpot Cloud 26.8.0.cl adds a Spotter *onboarding* experience [.version-badge.new]#New# that displays starter prompts to guide new users when they first open an embedded Spotter session. Starter prompts are hidden by default in embedded mode. + +To enable starter prompts, set `enableStarterPrompts` to `true`: + +// SOURCE: src/embed/conversation.ts confirmed property @version SDK: 1.51.0 +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + // Show onboarding starter prompts to new users (default: false) + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + enableStarterPrompts: true, +}); +spotterEmbed.render(); +---- + +// SOURCE: SCAL-299746, PR https://github.com/thoughtspot/visual-embed-sdk/pull/450 +=== New Action IDs for Spotter chat controls + +// TODO: [WRITER] Verify these three Action enum values are present in the published SDK 1.51.0 types.ts. +// PR reference: https://github.com/thoughtspot/visual-embed-sdk/pull/450 +// Previous workaround (CSS selectors) documented in the MCP connectors section below is now superseded. +Visual Embed SDK 1.51.0 adds three new `Action` enum values to control Spotter chat interface elements [.version-badge.new]#New#: + +[width="100%",cols="2,3"] +[options="header"] +|==== +|Action ID |Controls +|`Action.SpotterChatConnectors` |The MCP Connectors menu in the Spotter prompt panel +|`Action.SpotterChatConnectorResources` |The *+* (Add resources) icon in the Spotter prompt panel +|`Action.SpotterChatModeSwitcher` |The mode switcher control in the Spotter chat interface +|==== + +Use these action IDs with `hiddenActions` or `disabledActions` to control visibility of these interface elements without requiring CSS workarounds. + +Example — hide the MCP Connectors menu and resource icon: + +[source,JavaScript] +---- +import { + SpotterEmbed, + Action, + AuthType, + init, +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/token').then(r => r.json()).then(d => d.token), +}); + +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + updatedSpotterChatPrompt: true, + // Hide MCP connector controls using Action IDs (SDK 1.51.0+) + // Replaces CSS-selector workaround documented in earlier SDK versions. + hiddenActions: [ + Action.SpotterChatConnectors, + Action.SpotterChatConnectorResources, + ], +}); +spotterEmbed.render(); +---- + +[NOTE] +==== +Prior to SDK 1.51.0, hiding the MCP Connectors menu and the *+* icon required CSS selector workarounds. The `Action.SpotterChatConnectors` and `Action.SpotterChatConnectorResources` action IDs introduced in SDK 1.51.0 are the recommended approach. The CSS workaround documented in the xref:embed-spotter.adoc#mcp-connectors[MCP connectors] section remains functional but is no longer the preferred method. +==== + +// ============================================================ +// END OF NEW 26.8.0.cl CONTENT +// ============================================================ + == Before you begin To embed Spotter, you need the following access and setup: @@ -271,7 +470,7 @@ const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use the `enablePastConversationsSidebar` property within the `spotterSidebarConfig` object instead. When both properties are defined, the value in `spotterSidebarConfig` takes precedence. ==== - +[#mcp-connectors] ==== 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. @@ -282,7 +481,12 @@ If the new prompt interface in Spotter 3 is enabled, the Spotter page displays t 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. ==== -Currently, the Visual Embed SDK does not provide any attributes or action IDs to hide these elements. As a workaround, you can use CSS selectors to hide these elements: +// SOURCE: SCAL-299746, PR https://github.com/thoughtspot/visual-embed-sdk/pull/450 +// TODO: [WRITER] Update the NOTE below once SDK 1.51.0 is confirmed published — +// the Action ID approach is now the recommended method; the CSS workaround is a fallback only. +In Visual Embed SDK 1.51.0 and later, use `Action.SpotterChatConnectors` and `Action.SpotterChatConnectorResources` to hide these elements. See xref:embed-spotter.adoc#whats-new-26-8[What's new in 26.8.0.cl] for details and a code example. + +For earlier SDK versions, you can use CSS selectors as a workaround: [source,JavaScript] ---- From 838d4d0cb1dac1b2728e89b28c350c8bbac81c67 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Sat, 11 Jul 2026 10:11:05 +0530 Subject: [PATCH 30/63] docs(26.8.0.cl): add 26.8.0.cl changes section --- modules/ROOT/pages/embed-pinboard.adoc | 406 +------------------------ 1 file changed, 1 insertion(+), 405 deletions(-) diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 3d8d67eee..ec6077f68 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -1,405 +1 @@ -= Embed a Liveboard -:toc: true -:toclevels: 2 - -:page-title: Embed Liveboards -:page-pageid: embed-liveboard -:page-description: You can use the LiveboardEmbed SDK library to embed a ThoughtSpot Liveboard in your app and use it for live insights - -This page explains how to embed a ThoughtSpot Liveboard in your web page, portal, or application. - -A ThoughtSpot Liveboard is an interactive dashboard that presents a collection of visualizations pinned by a user. - -== Import the LiveboardEmbed package - -Import the `LiveboardEmbed` SDK library to your application environment: - -**npm** -[source,JavaScript] ----- -import { - LiveboardEmbed, - AuthType, - init, - prefetch, - EmbedEvent -} -from '@thoughtspot/visual-embed-sdk'; ----- - -**ES6** -[source,JavaScript] ----- -