diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index da7ec9f9f..2bddda0fc 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,10 +8,182 @@ 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/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. +// 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 +// 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 the embed mode. + +When enabled, the SDK provides the following controls to customize the Spotter interface: + +Custom labels (in `SpotterSidebarViewConfig`):: +* `spotterAnalystLabel` + +Custom singular label for the Analyst entity. Default: `Analyst`. +* `spotterAnalystsLabel` + +Custom label for the Analysts sidebar section. Default: `Analysts`. + +Starter prompts (in `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`. + +// 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 at authoring time. + +Action IDs for Analyst actions (in `hideActions` or `disableActions`):: + +* `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. + + +`loaderTips`:: +Custom array of `SpotterVizLoaderTip` objects displayed as tips during the SpotterViz loading state. Replaces the default loading tips. + + +`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?', + 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'); +---- + +[source,JavaScript] +---- +// 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 -[width="100%", cols="1,4"] +[width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW FEATURE# a| @@ -23,6 +195,7 @@ A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `Ap To customize app interactions, visibility of the UI elements, and style and appearance of the SpotterViz panel, the SDK also introduces CSS variables, action IDs, and embed and host event identifiers. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + |[tag greenBackground]#NEW FEATURE# a| [discrete] @@ -45,13 +218,12 @@ customizations to the new answers from an embedded Search data interface at init The `visualOverrides` object provides the following customization controls to modify the chart and table display: -* `legend`: control legend visibility, position, and color palette of charts. +* `legend` to control legend visibility, position, and color palette of charts. * `dataLabel` attribute for data labels and per-column label filters. -* `display` attributes for such as regression line overlay and grid line visibility in charts and table themes and content density in tables. +* `display` attributes such as regression line overlay and grid line visibility in charts, and table themes and content density in tables. * `axis` property for axis name and label visibility and fixed y-axis range. -* `columns` property for per-column series color and conditional formatting rules. -* `updateMaskPaths` property for partial updates -* `columns` property for column visibility, text wrapping, conditional formatting, and column summary in tables. +* `columns` property for per-column series color and conditional formatting rules in charts, and column visibility, text wrapping, conditional formatting, and column summary in tables. +* `updateMaskPaths` property for partial updates. For more information, see xref:viz-overrides.adoc[Visualization overrides]. |[tag greenBackground]#NEW FEATURE# a| @@ -86,7 +258,6 @@ For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploa |==== - == Version 1.48.x, May 2026 [width="100%" cols="1,4"] |==== @@ -155,8 +326,15 @@ EmbedEvent:: 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. +Emits when a user selects a different Personalized View on an embedded Liveboard, or resets to the default view. For more information, see xref:EmbedEvent.adoc#_changepersonalizedview[EmbedEvent reference documentation]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Personalized View selection via host event +The SDK introduces `HostEvent.SelectPersonalizedView` to programmatically switch the active Personalized View on an embedded Liveboard from the host application. For more information, see xref:HostEvent.SelectPersonalizedView[HostEvent reference documentation]. HostEvent:: * `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + @@ -177,7 +355,6 @@ The following events are deprecated and replaced with new event IDs. * `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. * `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. - |==== @@ -997,7 +1174,6 @@ Can be used to show or hide the *Verified Liveboard* banner. * `hidehomepageleftnav` * `hideorgswitcher` * `reorderedhomepagemodules` -* `hiddenhomeleftnavitems` * `HomeLeftNavItem` For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. @@ -1007,7 +1183,7 @@ For more information, see xref:full-app-customize.adoc[Customize full applicatio 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. +The following TML menu actions are now grouped under the **TML** sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. * Export TML * Edit TML @@ -1272,7 +1448,6 @@ Use the following action enumeration members instead of `Action.Download` to sho * `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` + @@ -1314,7 +1489,6 @@ 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") { @@ -1819,7 +1993,7 @@ For more information, see xref:push-data-to-external-app.adoc#large-dataset[Call |==== |[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`. +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]. diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index 4f5f8a246..347aa02bb 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -11,6 +11,7 @@ Embed ThoughtSpot in a web app * link:{{navprefix}}/tsembed[Quickstart guide] * link:{{navprefix}}/embed-ai-search-analytics[Embed AI Search and Analytics] ** link:{{navprefix}}/embed-spotter[Embed Spotter experience] +*** link:{{navprefix}}/customize-spotter-embed[Customize Spotter interface] ** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent] * link:{{navprefix}}/embed-liveboard[Embed Analytics] ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index cf7312ff9..1220e40da 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -226,6 +226,7 @@ REST APIs *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] *** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] +*** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] *** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^] *** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] ** link:{{navprefix}}/style-customization-apis[Style customization APIs] @@ -234,6 +235,7 @@ REST APIs ** link:{{navprefix}}/collections[Collections ^BETA^] ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] +** link:{{navprefix}}/input-tables-api[Input Tables API] ** link:{{navprefix}}/runtime-sort[Runtime sorting] * link:{{navprefix}}/manual-translation-api[Manual translations] * link:{{navprefix}}/webhooks-rest-api[Webhook APIs] @@ -244,6 +246,7 @@ REST API SDK * link:{{navprefix}}/rest-api-sdk[Overview] * link:{{navprefix}}/rest-api-sdk-typescript[TypeScript SDK] * link:{{navprefix}}/rest-api-sdk-java[Java SDK] +* link:{{navprefix}}/python-sdk[Python SDK] * link:{{navprefix}}/rest-apiv2-js[REST API v2.0 in JavaScript] [.sidebar-title] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index 62dc5391c..8f86700a6 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -20,29 +20,34 @@ REST APIs *** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] *** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] ** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] +** link:{{navprefix}}/runtime-sort[Runtime sorting] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] *** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] +*** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] *** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^] *** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] -** link:{{navprefix}}/style-customization-apis[Style customization APIs] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] ** link:{{navprefix}}/collections[Collections ^BETA^] ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] -** link:{{navprefix}}/runtime-sort[Runtime sorting] +** link:{{navprefix}}/input-tables-api[Input Tables API] ** link:{{navprefix}}/manual-translation-api[Manual translations] +** link:{{navprefix}}/style-customization-apis[Style customization APIs] ** link:{{navprefix}}/webhooks-rest-api[Webhook APIs] + + [.sidebar-title] REST API SDK * link:{{navprefix}}/rest-api-sdk[Overview] * link:{{navprefix}}/rest-api-sdk-typescript[TypeScript SDK] * link:{{navprefix}}/rest-api-sdk-java[Java SDK] +* link:{{navprefix}}/python-sdk[Python SDK] * link:{{navprefix}}/rest-apiv2-js[REST API v2.0 in JavaScript] [.sidebar-title] diff --git a/modules/ROOT/pages/customize-css-styles.adoc b/modules/ROOT/pages/customize-css-styles.adoc index 523961072..067cd0da9 100644 --- a/modules/ROOT/pages/customize-css-styles.adoc +++ b/modules/ROOT/pages/customize-css-styles.adoc @@ -8,7 +8,6 @@ The xref:css-customization.adoc[ThoughtSpot CSS customization framework] defines a number of variables for applying styles throughout embedded ThoughSpot components. - == Application-wide settings The following example shows the supported variables: @@ -43,6 +42,25 @@ The navigation panel appears at the top of the application page. |`--ts-var-search-data-button-font-family`| Font of the text on the *Search data* button. |====== +[#left-nav-css-vars] +=== Left navigation panel +Use the following CSS variables to customize the left navigation panel in full application embedding. + +[width="60%", cols="3,4"] +[options="header"] +|==== +|Variable |Description +|`--ts-var-left-nav-background` |Background color of the left navigation panel. +|`--ts-var-left-nav-active-tab-background` |Background color of the active tab in the left navigation panel. +|`--ts-var-left-nav-active-tab-border-color` |Border color of the active tab in the left navigation panel. +|`--ts-var-left-nav-section-title-color` |Font color of section title labels in the left navigation panel. +|`--ts-var-left-nav-item-color` |Font color of navigation items in the left navigation panel. +|`--ts-var-left-nav-item-selection-color` |Font color of the selected navigation item. +|`--ts-var-left-nav-item-selection-background` |Background color of the selected navigation item. +|`--ts-var-left-nav-tab-icon-active-color` |Icon color of the active tab in the left navigation panel. +|`--ts-var-left-nav-tab-icon-inactive-color` |Icon color of inactive tabs in the left navigation panel. +|==== + == Menu elements CSS Variables for **More** menu image:./images/icon-more-10px.png[the more options menu], contextual menu, and dropdown selection panels. The *More* menu appears on Liveboard, visualization, answers, SpotIQ, and several other application pages. Contextual menu appears when you right-click on a data point on a chart or table. diff --git a/modules/ROOT/pages/customize-homepage-full-embed.adoc b/modules/ROOT/pages/customize-homepage-full-embed.adoc index 70d9b1bbf..79f8605c3 100644 --- a/modules/ROOT/pages/customize-homepage-full-embed.adoc +++ b/modules/ROOT/pages/customize-homepage-full-embed.adoc @@ -4,18 +4,13 @@ :page-title: Customize home page experience :page-pageid: customize-homepage-experience -:page-description: Customize the home page experience by including or excluding specific modules and arrange them as needed in full application embedding +:page-description: Customize the home page experience by including or excluding specific modules and arranging them as needed in full application embedding -Developers can customize the home page experience in full application embedding to show either the classic layout or the new modular home page. +Developers can customize the home page experience in full application embedding to show either the V3 modular layout or the V4 focused home page. [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. -==== - -[NOTE] -==== -The focused homepage experience is an Early Access feature and is disabled by default. To enable this experience in your embedding application, ensure that the feature is enabled on your ThoughtSpot instance and in the Visual Embed SDK. +Starting from Visual Embed SDK 1.51.0, the classic v1 and v2 navigation and homepage experience are deprecated. Deployments using full application embed will be upgraded to the V3 navigation and home page experience. When your application is switched to V3 experience, you can choose to use the `HomePage.ModularWithStylingChanges` (V3) or `HomePage.Focused` (V4) experience. ==== == Home page layout @@ -27,17 +22,19 @@ The SDK provides the xref:HomePage.adoc[homePage] attribute to set the desired h * `homePage: HomePage.Focused` [earlyAccess eaBackground]#Early Access# + Enables the V4 home page experience. * `homePage: HomePage.ModularWithStylingChanges` + -Enables the V3 modular home page experience with customizable components, styling options, and enhanced layout. -* `homePage: HomePage.Modular` + -Enables the basic modular home page experience with customizable components. +Enables the V3 modular home page experience with customizable components, styling options, and enhanced layout. This experience includes charts in the **Watchlist** module that are arranged horizontally. Each chart includes menu actions to remove the KPI charts from the watchlist and create alerts, and allows drag-and-drop reordering. + +//// +=== V3 home page experience +The V3 home page experience improves the layout with the following enhancements: + +* -Both V2 and V3 home page experience show customization modules. The V3 home page experience improves the layout with the following enhancements: -* The charts in the **Watchlist** module are arranged horizontally. Each chart includes menu actions to remove the KPI charts from the watchlist and create alerts, and allows drag-and-drop reordering. + [.bordered] [.widthAuto] -image::./images/watchlistv3andv2.png[V2 and V3 Watchlist module] +image::./images/watchlistv3andv2.png[V3 Watchlist module] * The **Trending** module displays separate lists for Liveboards and Answers objects. Both these lists show the objects trending for the last 15 days, or based on the overall views, or both. + [.bordered] @@ -51,6 +48,7 @@ image::./images/favoritesV3.png[V2 and V3 Trending module, scaledwidth=50%] * Style and CSS improvements to the **Learning** module. In both V2 and V3, the SDK allows customization to include or exclude modules, change their order, and adjust the overall layout. +//// [#_enable_focused_home_page] === V4 focused home page experience @@ -79,8 +77,43 @@ const embed = new AppEmbed("#embed", { ---- == Customization settings for home page -The following customization settings are available for the modular home page in the V2 and V3 experience modes. +The following customization settings are available for the modular home page in the V3 and V4 experience modes. +[width="100%", cols="5,^3,^3"] +[options="header"] +|==== +|Feature |V3 experience + +`HomePage.ModularWithStylingChanges` |V4 experience + +`HomePage.Focused` +|Default experience as of 26.8.0.cl +|[tag greenBackground tick]#✓# Default +|[tag redBackground tick]#x# Not default +|`hideHomepageLeftNav` + +Hides the left navigation panel on the home page. +|[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported +|`hiddenHomepageModules` + +Hides specific modules on the home page. +|[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported +|`reorderedHomepageModules` + +Reorders modules on the home page. +|[tag greenBackground tick]#✓# Supported +|[tag redBackground tick]#x# Not supported +|`homePageModules` + +Specifies which modules to show on the home page. +|[tag greenBackground tick]#✓# Supported +|[tag redBackground tick]#x# Not supported +|Left navigation panel customization +|[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported +|Custom reordering of left nav items +|[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported +|==== + + +//// [width="100%", cols="2,2,2,2"] [options='header'] |==== @@ -122,7 +155,7 @@ Hides xref:customize-nav-full-embed.adoc#_customize_the_left_navigation_panel_on | [tag greenBackground tick]#✓# Supported |==== -//// + [width="100%", cols="2,2,2,2,2"] [options='header'] |==== @@ -175,6 +208,82 @@ In the V2 and V3 experience modes, the home page includes sections such as *Watc The `hiddenHomepageModules` and `reorderedHomepageModules` attributes support the following settings: +=== `hiddenHomepageModules` + +[source,TypeScript] +---- +hiddenHomepageModules?: HomepageModule[]; +---- + +Hides specific modules on the home page. Applies to V3 (`HomePage.ModularWithStylingChanges`) and V4 (`HomePage.Focused`) home page experiences. + +// SOURCE: visual-embed-sdk PR #530 — updated note in types.ts JSDoc +// TODO: [WRITER] Confirm which HomepageModule values apply to V4 experience only. + +=== `reorderedHomepageModules` + +[source,TypeScript] +---- +reorderedHomepageModules?: HomepageModule[]; +---- + +Reorders modules on the home page. Applies to V3 (`HomePage.ModularWithStylingChanges`) only. + +// SOURCE: visual-embed-sdk PR #530 +// TODO: [WRITER] Confirm with product team whether reordering is available in V4. + +=== `homePageModules` + +[source,TypeScript] +---- +homePageModules?: HomepageModule[]; +---- + +Specifies which modules to show on the home page. Applies to V3 (`HomePage.ModularWithStylingChanges`) only. + +// TODO: [WRITER] Confirm with product team whether homePageModules is available in V4. + +== `HomepageModule` enum values + +// SOURCE: SCAL-312731, src/types.ts +// TODO: [WRITER] Confirm the full list of HomepageModule enum values and +// which apply to V3 only vs both V3 and V4 with the SDK/product team. + +[width="100%", cols="3,6"] +[options="header"] +|==== +|Value |Description +|`HomepageModule.Watchlist` |The Watchlist module showing pinned objects. +|`HomepageModule.MyLibrary` |The My Library module showing user's content. +|`HomepageModule.Learning` |The Learning module with onboarding content. +|`HomepageModule.Trending` |The Trending module showing trending content. +|`HomepageModule.Answers` |The Answers module showing recent Answers. +// TODO: [WRITER] Verify complete enum list — add all values from types.ts. +|==== + +== `HomeLeftNavItem` enum values + +// SOURCE: visual-embed-sdk PR #530 — updated class-level JSDoc in types.ts +// "Classic (V1) and Modular (V2) home page experiences are deprecated. +// This attribute applies to V3 (ModularWithStylingChanges) and V4 (Focused)." + +Use `HomeLeftNavItem` to customize the left navigation panel items on the home page. +Applies to V3 (`HomePage.ModularWithStylingChanges`) and V4 (`HomePage.Focused`) home page experiences. + +[width="100%", cols="3,6"] +[options="header"] +|==== +|Value |Description +|`HomeLeftNavItem.Home` |The Home item in the left navigation panel. +|`HomeLeftNavItem.Liveboards` |The Liveboards item in the left navigation panel. +|`HomeLeftNavItem.Answers` |The Answers item in the left navigation panel. +|`HomeLeftNavItem.SpotIQ` |The SpotIQ item in the left navigation panel. +|`HomeLeftNavItem.MonitorAlerts` |The Monitor Alerts item in the left navigation panel. +|==== + + + +//// [width="100%", cols="2,2,2,2"] [options='header'] |=== @@ -219,6 +328,7 @@ For the **Watchlist** section, which is used for KPI monitoring. | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported |=== +//// === Customize home page modules in the V3 experience The following example shows the configuration properties for customizing the home page modules: @@ -254,6 +364,7 @@ const embed = new AppEmbed("#embed", { }); ---- +//// === Customize home page modules in the V2 experience The following example shows the configuration properties for customizing the home page modules in the V2 experience: @@ -282,15 +393,15 @@ The following example shows the configuration properties for customizing the hom //... Other view configuration properties }); ---- - +//// [#_search_experience_on_home_page] === Customize the search experience on home page You can set the search experience on the home page to function as an object search bar that allows finding popular objects, or as an AI search interface that allows natural language queries or Spotter sessions. You can also choose to hide it from the home page. To configure your preference, specify the following values in the `homePageSearchBarMode` attribute. [width="100%", cols="4,8"] -[options='header'] -|===== +[options="header"] +|==== |Search bar mode|Description |`HomePageSearchBarMode.AI_ANSWER` | Sets the natural language search bar that allows queries in natural language. @@ -299,8 +410,7 @@ If Spotter is enabled on your instance, you can use this setting to set the Spot |`HomePageSearchBarMode.NONE` a| 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. To hide the search bar on the home page, you can also use the xref:customize-homepage-full-embed.adoc#_control_the_visibility_of_home_page_modules[homepageModule: HomepageModule.Search] setting. -|| -|===== +|==== [NOTE] ==== @@ -316,15 +426,15 @@ V3 experience:: ---- import { AppEmbed, - PrimaryNavbarVersion // Enum for V3 navigation experience + PrimaryNavbarVersion, // Enum for V3 navigation experience HomePage, // Enum for home page experience settings HomePageSearchBarMode // Import the enum for search bar mode options } from '@thoughtspot/visual-embed-sdk'; const embed = new AppEmbed("#embed", { discoveryExperience: { - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable v3 experience - homePage: HomePage.ModularWithStylingChanges // Enable v3 home page experience + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 experience + homePage: HomePage.ModularWithStylingChanges // Enable V3 home page experience }, // Set the home page search bar to show the Spotter / AI search bar homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER @@ -332,17 +442,23 @@ const embed = new AppEmbed("#embed", { }); ---- -V2 experience:: + +V4 experience:: [source,javascript] ---- import { AppEmbed, + PrimaryNavbarVersion, // Enum for V3 navigation experience + HomePage, // Enum for home page experience settings HomePageSearchBarMode // Import the enum for search bar mode options } from '@thoughtspot/visual-embed-sdk'; const embed = new AppEmbed("#embed", { - modularHomeExperience: true, // Enable v2 modular home page experience + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 experience + homePage: HomePage.Focused, // Enable V4 home page experience + }, // Set the home page search bar to show the Spotter / AI search bar homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER // Other view configuration attributes @@ -350,24 +466,6 @@ const embed = new AppEmbed("#embed", { ---- -Classic (V1) experience:: - -[source,javascript] ----- -import { - AppEmbed, - HomePageSearchBarMode // Import the enum for search bar mode options -} from '@thoughtspot/visual-embed-sdk'; - -const embed = new AppEmbed("#embed", { - // Set the home page search bar to show the Spotter / AI search bar - homePageSearchBarMode: HomePageSearchBarMode.aiAnswer, - // Disable the unified search experience - isUnifiedSearchExperienceEnabled: false, - //... other embed view configuration attributes -}); ----- - //// ==== Enable AI Search To set AI Search as the default search experience on the Home page, use the settings shown in the following examples. diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc index cb4b45ceb..b90c71995 100644 --- a/modules/ROOT/pages/customize-nav-full-embed.adoc +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -8,44 +8,24 @@ You can customize the navigation experience and the visibility of navigation menu elements using the Visual Embed SDK. -[div announcementBlock] --- [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. --- +==== +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. +==== == Navigation experience -The navigation structure in ThoughtSpot UI varies based on the UI experience mode set in your embed view. - -[width="100%", cols="2,4"] -[options='header'] -|==== -|UI experience| Navigation options -|Classic (V1) experience a|A standard top navigation bar with the following components: + +Both V3 and V4 experience provide the following navigation experience: -* A horizontal application menu -* Help and user profile icons -* Org switcher - -|V2 experience a| -* Simplified top navigation structure. Includes the following components: + -** Object search bar -** The application selector to switch between different application contexts -** Help and profile icons -** Org switcher for instances with Orgs -* A left navigation panel for each application context. -|V3 experience -a| * Top navigation bar with a modern look and feel. Includes the following components: ** A hamburger icon for the sliding navigation overlay ** Object search bar -** Help and profile icons + +** Help and profile icons ** Org switcher * Left navigation ** A sliding left navigation panel controlled via the hamburger icon ** Persona-based app selection icons in the panel header ** Left navigation menu that adjusts its contents according to the application context -|==== + [NOTE] ==== @@ -56,58 +36,52 @@ The V4 focused home page experience (`HomePage.Focused`) uses the same navigatio The following customization settings are available for the top navigation bar. -[width="100%", cols="2,2,2,2"] -[options='header'] +[width="100%", cols="3,^2,^2"] +[options="header"] |==== | SDK property -| Classic (V1) experience -| V2 experience -| V3 experience -|`showPrimaryNavbar` + +| V3 experience + +`HomePage.ModularWithStylingChanges` +| V4 experience + +`HomePage.Focused` + +| `showPrimaryNavbar` + To show or hide the navigation experience. | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported -| [tag greenBackground tick]#✓# Supported - | `hideApplicationSwitcher` + To show or hide the application switcher. -| [tag redBackground tick]#x# Not supported | [tag greenBackground tick]#✓# Supported + -In V2 experience, hides the app selector in the top navigation bar. +Hides the app selection icons on the left navigation panel. | [tag greenBackground tick]#✓# Supported + -In the V3 experience, hides the app selection icons on the left navigation panel. +Hides the app selection icons on the left navigation panel. | `disableProfileAndHelp` + -To show or hide the help and user profile icons in top navigation bar. -| [tag greenBackground tick]#✓# Supported +To show or hide the help and user profile icons in the top navigation bar. | [tag greenBackground tick]#✓# Supported + Also hides or shows the *Help* menu on the left navigation panel of the home page. -| [tag greenBackground tick]#✓# Supported + +| [tag greenBackground tick]#✓# Supported | `hideOrgSwitcher` + To show or hide the Org switcher. | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported -| [tag greenBackground tick]#✓# Supported | `hideNotification` + To show or hide the notification (bell) icon. -| [tag redBackground tick]#x# Not supported -| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `hideObjectSearch` + To show or hide the object search bar in the top navigation bar. -| __Not applicable__ + -The object search bar is hidden by default. | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `hideHamburger` + To show or hide the hamburger icon in the top navigation bar. -| __Not applicable__ -| __Not applicable__ | [tag greenBackground tick]#✓# Supported + -Hides the hamburger icon available on pages where the left navigation panel is hidden by default. +Hides the hamburger icon available on pages where the left navigation +panel is hidden by default. +| [tag greenBackground tick]#✓# Supported |==== === Example @@ -117,15 +91,11 @@ The following example hides the icons in the top navigation and the application [source,JavaScript] ---- const embed = new AppEmbed("#embed", { - //... V3 experience attributes - // Show navigation bar + //... V3 experience attributes showPrimaryNavbar: true, hideApplicationSwitcher: true, - // Hide Help and User Profile icons in top navigation disableProfileAndHelp: true, - // Hide object search bar in top navigation hideObjectSearch: true, - // Hide the alert icon in top navigation hideNotification: true, //... other attributes }); @@ -135,161 +105,89 @@ const embed = new AppEmbed("#embed", { In ThoughtSpot application, users can open the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage#command-palette[command palette] by pressing kbd:[Cmd+K] on macOS or kbd:[Ctrl+K] on Windows to quickly navigate to objects and perform actions. However, when you embed ThoughtSpot, this feature is disabled and embedded pages include only the standard object search experience. == Customize the left navigation panel on the home page -In the V2 and V3 experience modes, the left navigation panel on the *Insights* > *Home* page includes menu items such as *Answers*, *Liveboards*, *SpotIQ Analysis*, *Monitor Subscriptions*, and more. You can hide this navigation panel by setting the `hideHomepageLeftNav` property to `true` in the SDK. Note that this attribute hides the left navigation only on the home page. +In the V3 and V4 experience modes, the left navigation panel on the *Insights* > *Home* page includes menu items such as *Spotter*, *Answers*, *Liveboards*, *SpotIQ Analysis*, *Monitor Subscriptions*, and more. You can hide this navigation panel by setting the `hideHomepageLeftNav` property to `true` in the SDK. Note that this attribute hides the left navigation only on the home page. If you want to include the left navigation, but hide only a specific section in the *Insights* panel, use the `hiddenHomeLeftNavItems` property and specify the menu items to hide. The allowed values for `hiddenHomeLeftNavItems` are listed in the following table: -[width="100%", cols="2,2,2,2"] -[options='header'] - -|=== -|Allowed values -| Classic (V1) experience -| V2 experience -| V3 experience +[width="100%", cols="3,^2,^2"] +[options="header"] +|==== +| Allowed values +| V3 experience + +`HomePage.ModularWithStylingChanges` +| V4 experience + +`HomePage.Focused` | `HomeLeftNavItem.Create` + -To show or hide the `+` icon that allows users to create a Liveboard or Answer in the *Insights* panel. -| __Not applicable__ -| __Not applicable__ +To show or hide the `+` icon that allows users to create a +Liveboard or Answer in the *Insights* panel. +| [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Home` + To show or hide the *Home* menu in the *Insights* panel. -| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported + | `HomeLeftNavItem.Spotter` + -To show or hide the *Spotter* menu item in the *Insights* panel. -| __Not applicable__ -| __Not applicable__ +To show or hide the *Spotter* menu item in the *Insights* panel. +| [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.SearchData` + To show or hide the *Search Data* in the *Insights* panel. -| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Liveboards` + To show or hide the *Liveboards* menu in the *Insights* panel. -| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Answers` + To show or hide the *Answers* menu in the *Insights* panel. -| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported -| `HomeLeftNavItem.LiveboardSchedules` + -To show or hide the *Liveboard Schedules* menu in the *Insights* panel. -| __Not applicable__ +| `HomeLeftNavItem.MonitorAlerts` + +To show or hide the *Monitor* > *Alerts* menu in the *Insights* panel. | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported -| `HomeLeftNavItem.MonitorSubscription` + -To show or hide the *Monitor subscriptions* in the *Insights* panel. -| __Not applicable__ -| [tag greenBackground tick]#✓# Supported -| [tag greenBackground tick]#✓# Supported -| `HomeLeftNavItem.SpotIQAnalysis` + -To show or hide the *SpotIQ analyses* in the *Insights* panel. -| __Not applicable__ +| `HomeLeftNavItem.MonitorSubscriptions` + +To show or hide the *Monitor* > *Subscriptions* menu in the +*Insights* panel. | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported -| `HomeLeftNavItem.Favorites` + -To show or hide the `Favorites` section in the *Insights* panel. -| __Not applicable__ -| __Not applicable__ -| [tag greenBackground tick]#✓# Supported -|=== -== Examples -The following sections show code samples for customizing the default left navigation panel in the *Insights* section and the home page. - -=== V3 experience - -[source,JavaScript] ----- -import { - AppEmbed, // Main class to embed the full ThoughtSpot app - HomePage, // Enum for home page experience setting - PrimaryNavbarVersion, // Enum for navigation bar version - HomeLeftNavItem, // Enum for left navigation items -} from '@thoughtspot/visual-embed-sdk'; - -const embed = new AppEmbed("#embed", { - discoveryExperience: { - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation - homePage: HomePage.ModularWithStylingChanges, // Enable V3 modular home page - }, - // Show navigation bar - showPrimaryNavbar: true, - // Show left navigation on home page - hideHomepageLeftNav: false, - // Hide SpotIQ analysis and Favorites menu options - hiddenHomeLeftNavItems: [ - HomeLeftNavItem.Favorites, - HomeLeftNavItem.SpotIQAnalysis - ], - //... other embed view configuration attributes -}); ----- - -=== V2 experience +| `HomeLeftNavItem.SpotIQAnalysis` + +To show or hide the *SpotIQ Analysis* menu in the *Insights* panel. +| [tag greenBackground tick]#✓# Supported +| [tag redBackground tick]#x# Not supported -[source,JavaScript] ----- -import { - AppEmbed, // Main class to embed the full ThoughtSpot app - HomeLeftNavItem, // Enum for left navigation items -} from '@thoughtspot/visual-embed-sdk'; -const embed = new AppEmbed("#embed", { - // Enable the V2 navigation experience - modularHomeExperience: true, - // Show left navigation panel - hideHomepageLeftNav: false, - // Hide SpotIQ analysis and Monitor subscriptions menu options - hiddenHomeLeftNavItems: [ - HomeLeftNavItem.MonitorSubscription, - HomeLeftNavItem.SpotIQAnalysis - ], - //... other embed view configuration attributes -}); ----- - -== Customize the Help menu +| `HomeLeftNavItem.Learning` + +To show or hide the *Learning* menu in the *Insights* panel. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported -If you want to include the help menu and link:https://docs.thoughtspot.com/cloud/latest/customize-help[add custom links, window=_blank] to it, ensure that the top navigation bar is visible and `disableProfileAndHelp` is set to `false`. -By default, the help menu in the embedded view shows the legacy information center controlled using Pendo. To enable the new information center and add custom links, set `enablePendoHelp` to `false`. +| `HomeLeftNavItem.LiveboardSchedules` + +To show or hide the *Scheduled Liveboards* section in the +*Insights* panel. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported -To add custom links to the help menu, use the customization options in the **Admin settings** > **Help customization** page. For more information, refer to the link:https://docs.thoughtspot.com/cloud/latest/customize-help[ThoughtSpot Product Documentation]. +|==== -[source,JavaScript] ----- -const embed = new AppEmbed("#embed", { - // Display the top navigation bar - showPrimaryNavbar: true, - // Show the profile and help icons in the top navigation bar. - disableProfileAndHelp: false, - // Use the new ThoughtSpot information center for help and support. - enablePendoHelp: false, - //... other embed view configuration attributes -}); ----- -== Additional resources -See also: +== Related resources -* xref:full-app-customize.adoc[Customize full application embed] -* xref:full-embed.adoc[Embed full application] +* xref:full-app-customize.adoc[Customize full application embedding] +* xref:customize-homepage-full-embed.adoc[Customize home page experience] * xref:AppViewConfig.adoc[AppViewConfig reference page] * xref:HostEvent.adoc[Host events] * xref:EmbedEvent.adoc[Embed Events] diff --git a/modules/ROOT/pages/customize-spotter-embed.adoc b/modules/ROOT/pages/customize-spotter-embed.adoc new file mode 100644 index 000000000..762f4445d --- /dev/null +++ b/modules/ROOT/pages/customize-spotter-embed.adoc @@ -0,0 +1,368 @@ += Customizing the Spotter embed view +:toc: true +:toclevels: 2 + +:page-title: Customizing the Spotter embed view +:page-pageid: customize-spotter-embed +:page-description: You can customize the SpotterEmbed experience using the customization options available in the Visual Embed SDK. + +When you xref:embed-spotter.adoc[embed Spotter] in your application, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding. + +== Spotter UI +If you have embedded Spotter Classic or Spotter 2, the initial page includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session. + +[.widthAuto] +[.bordered] +image::./images/spotter-embed-legacy.png[Spotter embed] + +In Spotter 3 embedding, you can load the page with a pre-selected data source or use the *Auto mode* to allow Spotter to automatically discover and select a relevant data model for user queries. + +**Default view**: + +[.widthAuto] +[.bordered] +image::./images/spotter3-legacy-interface.png[Spotter 3 interface] + +**With Auto mode enabled**: + +[.widthAuto] +[.bordered] +image::./images/spotter3-leagcy-interface-automode.png[Spotter 3 interface] + +[NOTE] +==== +When Auto mode is enabled, **Preview data** and **Data Model instructions** options will not be available. +==== + +== Chat interface +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: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed configuration attributes + // Enable the updated Spotter chat prompt experience. + updatedSpotterChatPrompt: true, +}); +---- + +[.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 and customize the chat history sidebar, configure the chat history properties in the `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, // 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 + }, +}) +---- + +[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 +ThoughtSpot allows users to create and manage AI agents (Analysts) directly within the Spotter interface. These AI agents or bots are referred to as link:https://docs.thoughtspot.com/cloud/latest/spotter-analysts[Spotter Analysts, window=_blank]. Each Analyst is scoped to a data model and can be configured with custom instructions, personas, and conversation starters. + +If you have Spotter Analysts on your ThoughtSpot instance, you can make these available to your embedding application users. + +=== Spotter Analyst panel +If your ThoughtSpot instance has Spotter Analysts, the Spotter Analysts panel and dashboard are visible by default in the Spotter sidebar in the embed view. To control the visibility of this panel in the embed view, use the `SpotterAnalystSidebar` action ID in the `disabledActions`, `hiddenActions`, or `visibleActions` arrays as needed. + +If Spotter Analysts are enabled in the embed view, you can use the following action IDs to show or hide the menu actions: + +* `Action.CreateAnalyst` + +Action ID for the **Create new** action in the Spotter Analysts page. +* `Action.EditAnalyst` + +Action ID for the Analyst edit option. +* `Action.CopyAnalyst` + +Action ID for the *Make a copy* action that creates a copy of the Analyst. +* `Action.ShareAnalyst` + +Action ID for the share action that allows sharing an Analyst with other users. +* `Action.DeleteAnalyst` + +Action ID for the delete option. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + hiddenActions: [ + Action.CreateAnalyst, + Action.DeleteAnalyst, + ], +}); +---- + +=== Analysts label strings +Use `spotterAnalystLabel` and `spotterAnalystsLabel` to replace the default "Analyst" and "Analysts" label text in the embedded Spotter interface with custom terminology suited to your application: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + // Custom label for a single Analyst (default: "Analyst") + spotterAnalystLabel: 'AI Assistant', + // Custom label for the Analysts section heading (default: "Analysts") + spotterAnalystsLabel: 'AI Assistants', +}); +---- + +== Quick search and deep analysis mode +When Spotter 3 experience is enabled on a ThoughtSpot instance, the Spotter interface displays a switcher to toggle between the Quick Search and Deep Analysis modes. + +To show, hide, or disable this feature in the embedded view, use the action ID, +`Action.SpotterChatModeSwitcher`. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + hiddenActions: [ + Action.SpotterChatModeSwitcher, + ], +}); +---- + +== Spotter starter prompts +ThoughtSpot allows users to preselect prompts and display these prompts in the Spotter interface for quick analysis. This feature is disabled by default in the embedded view. To enable this feature, contact ThoughtSpot Support. + +When this feature is enabled on your instance, you can use the `enableStarterPrompts` property in the `spotterChatConfig` object to display the starter prompts to your embedding application users. These prompts appear below the search bar when the users open the Spotter embedded view. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + spotterChatConfig: { + enableStarterPrompts: true, + }, +}); +---- + +[#mcp-connectors] +== MCP connectors and resource selection icon +If the Spotter 3 interface is enabled, the Spotter page displays the following options to connect external tools and resources for AI analytics. + +* Connector icon that allows you to connect to external applications such as Google Drive, Slack, Notion, Confluence, or Jira, which can be used as a data source in Spotter sessions. These connectors must be preconfigured by your ThoughtSpot administrator for your embedding deployments. +* Add files (+) icon for uploading files and resources for setting the conversation context. +* **Connectors** menu with a `+` icon in the prompt panel that lets your application users connect to external tools and resources. + +These integrations allow users to include both structured and unstructured data in their conversation sessions. + +To show, hide, or disable these options, use the following action IDs in the `disabledActions`, `hiddenActions`, or `visibleActions` arrays as needed: + +* `Action.SpotterChatConnectors` for the Connectors list. +* `Action.SpotterChatConnectorResources` for the connector resources section. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + hiddenActions: [ + Action.SpotterChatConnectors, + Action.SpotterChatConnectorResources, + ], +}); +spotterEmbed.render(); +---- + +[#fileUpload] +== 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 the **+ 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 spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + //... + spotterChatConfig: { + spotterFileUploadEnabled: true, + spotterFileUploadFileTypes: ['pdf', 'png', 'xlsx'], + }, +}); +---- + +//// +For earlier SDK versions, you can use CSS selectors as a workaround: + +[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 +}); +---- +//// + +== Spotter icon customization +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] + +=== Spotter logo and ThoughtSpot branding label +To hide the Spotter logo and branding in the chat interface and tool response, use the following `SpotterChatViewConfig` object properties: + +* `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 +} from '@thoughtspot/visual-embed-sdk'; + +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + 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', + }, +}); +---- + +== 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] +=== CSS variables for style customization +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", + }, + }, + }, + }, +}); +---- + +=== Text string customization +To replace text strings, you can use the `stringIDs` and `strings` properties in the content customization object. + +The following example shows how to replace "Spotter" and other text strings on the Spotter interface. + +[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", + } + } + } +}); +---- + +[#spotterMenuActions] +=== Menu elements and action visibility +The SDK provides action IDs to disable, show, or hide the following elements and menu actions via `disabledActions`, `visibleActions`, or `hiddenActions` arrays. + +For example, you can hide the *Preview data*, *Reset* in the prompt panel, or *Pin*, *Download*, and other actions from a Spotter-generated response. + +The following code sample disables actions and menu elements using the xref:embed-actions.adoc[`disabledActions`] array: + +[source,JavaScript] +---- + // 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]. + +== 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] diff --git a/modules/ROOT/pages/customize-style.adoc b/modules/ROOT/pages/customize-style.adoc index 45798283f..8f9d7c374 100644 --- a/modules/ROOT/pages/customize-style.adoc +++ b/modules/ROOT/pages/customize-style.adoc @@ -6,7 +6,7 @@ :page-pageid: customize-style :page-description: Rebrand embedded ThoughtSpot content -If you want to match the look and feel of embedded ThoughtSpot content with your core application, you can customize the ThoughtSpot application UI elements. Using style customization, you can create a uniform ThoughtSpot experience that complies with your company’s branding guidelines. +If you want to match the look and feel of embedded ThoughtSpot content with your core application, you can customize the ThoughtSpot application UI elements. Using style customization, you can create a uniform ThoughtSpot experience that complies with your company's branding guidelines. You can rebrand the ThoughtSpot interface elements such as the application logo, background color, and color scheme of visualizations. [NOTE] @@ -68,13 +68,16 @@ image::./images/style-applogo.png[Default Application Logo] + image::./images/style-widelogo.png[Wide application logo] ++ +// SOURCE: SCAL-319679 (doc task: SCAL-323307) — engineering commit 821c07db scaligent #64156 +// CHANGE: Updated wide logo recommended size from 330px by 100px to 250px by 50px (5:1 ratio) +// Effective from: ThoughtSpot Cloud 26.8.0.cl + [NOTE] ==== * The application logo (wide) appears on the login screen. - -* The recommended size is 330px by 100px. This will allow the system to preserve the aspect ratio of the uploaded logo image and prevent distortion. - +* The recommended size is 250px by 50px (5:1 aspect ratio). This allows the system to preserve the aspect ratio of the uploaded logo image and prevent distortion. +* The wide logo dimensions have changed in ThoughtSpot Cloud 26.8.0.cl and later versions. If you previously uploaded a logo sized at 330px by 100px, re-upload your logo at 250px by 50px to ensure it displays correctly on the login screen without distortion. * The accepted file formats for the logo image are jpg, jpeg, and png. ==== @@ -181,67 +184,42 @@ To change the color palette for charts: . To access the ThoughtSpot Developer portal, click *Develop* . Under *Customizations*, click *Styles*. -. Click the background color box under *Chart Color Palettes*. -. Click the color you would like to change in the *primary* color palette, and use the color menu to choose your new color. +. Click the color box under *Chart Color Palettes*. + -You can also add a HEX color code. -. Click the color you would like to change in the *secondary* color palette, and use the color menu to choose your new color. -You can also add a HEX color code. -+ -The colors from the secondary color palette are used after all of the primary colors from the primary palette have been exhausted. -Therefore, the secondary palette usually consists of secondary colors. - -=== Configure color rotation +image::./images/chart-colors.png[Chart Color Palettes] -If the chart requires only one color, ThoughtSpot selects a primary color depending on whether you enabled color rotation. The *Color rotation* feature determines whether single-color charts use a random primary color or always use the first primary color in the palette. If you enable Color Rotation, ThoughtSpot picks colors randomly and may choose any color from Primary 1 through Primary 6 in your color palette for single-color charts. If you disable Color Rotation, ThoughtSpot always chooses Primary 1. +. To choose a primary color, click the color box. ++ +image::./images/select-color.png[Select Primary Color] -If you disable color rotation, ThoughtSpot generates single-color charts in the order of your color palette, left to right. +. You can also add a HEX color code. +. To add more colors, click *Add Color*. +. To reset your chart colors to the ThoughtSpot default, click *Reset*. [#footer-text] == Customize footer text -You can customize the footer text in your ThoughtSpot instance to add your company-specific message. -To customize or rebrand the footer text, follow these steps: +You can add custom footer text to the ThoughtSpot UI. + +To customize footer text: . To access the ThoughtSpot Developer portal, click *Develop* . Under *Customizations*, click *Styles*. -. Click the text box under *Footer text* and enter the message. -+ -Your custom message will appear in the footer. - -//// -. Add `?customBrandingEnabled=true` to your application URL as shown in the following examples: -+ ----- -https://{ThoughtSpot-Host}/?customBrandingEnabled=true/#/ ----- -+ ----- -https://{ThoughtSpot-Host}/?customBrandingEnabled=true/#/pinboards ----- -. Go to *Admin* > *Application settings* > *Style customization* or *Develop* > *Customizations* > *Styles*. -+ -You require administrator or developer privilege to apply custom styles and footer text. -. Click the text box under *Footer text* and enter the message. -+ -Your custom message will appear in the footer. -. To enable footer text customization on your cluster by default, contact ThoughtSpot Support. -//// +. Add the footer text in the *Footer Text* box. -//// [#page-title] == Customize page title -To customize the page title displayed in the browser bar: +You can customize the page title that appears in the browser tab. + +To customize the page title: . To access the ThoughtSpot Developer portal, click *Develop* . Under *Customizations*, click *Styles*. -. Click the text box under *Page title*. -. Enter your new text message. -//// - -== Reset styles +. Add the page title in the *Page Title* box. -When you customize styles, the changes take effect after you refresh the browser. +== Related resources -To revert your changes, use the *Reset* button that appears when you move your cursor to the right of the style setting option. +* link:https://docs.thoughtspot.com/cloud/latest/style-customization[Style Customization in ThoughtSpot, window=_blank] +* xref:embed-liveboard.adoc[Embed Liveboards] +* xref:full-app-customize.adoc[Customize the full application] diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index b95b51895..f32d57f79 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -245,7 +245,7 @@ The default `file_format` is *CSV*. If you do not have .csv downloads enabled for your ThoughtSpot instance, select either `PDF` or `PNG` `file_format` to successfully download the report. Using any other format will cause the API to return an error. -For *CSV* downloads [earlyAccess eaBackground]#Early Access#, +For *CSV* downloads, * Each visualization is exported as a separate .csv file. * If multiple visualizations are selected, the downloaded report is a single compressed .zip file containing all .CSV files. @@ -269,14 +269,14 @@ curl -X POST \ }' ---- -For *XLSX* downloads [earlyAccess eaBackground]#Early Access#, +For *XLSX* downloads, * Visualization is exported as an Excel workbook (.xlsx). * If multiple visualizations are selected, the downloaded report is a single Excel workbook (.xlsx) containing each visualization in their individual tab. * A maximum of 255 tabs per .xlsx workbook are allowed. * It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. * Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. -* New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity. To enable this on your ThoughtSpot instance, contact ThoughtSpot Support. +* New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity. ===== Sample API payload for XLSX downloads @@ -299,12 +299,11 @@ For *PDF* downloads, you can specify additional parameters to customize the page You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages. -* `page_size = CONTINUOUS` [beta betaBackground]^Beta^ Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. +* `page_size = CONTINUOUS` Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. + When `page_size = CONTINUOUS`, the `include_filter_page` option works to show/hide the filter section in the PDF page (in a continuous PDF, there is no separate filter page, but the filters are included on the same page at the top). -* `zoom_level` [beta betaBackground]^Beta^ offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size = CONTINUOUS`. Valid values are integers in the range of 45 and 175. +* `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 = CONTINUOUS`. Valid values are integers in the range of 45 and 175. -To enable this on your ThoughtSpot instance, contact ThoughtSpot Support. ===== Sample API payload for PDF downloads @@ -335,11 +334,9 @@ curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ For *PNG* downloads, you can now define -* `image_resolution` [earlyAccess eaBackground]#Early Access# -* `image_scale` [earlyAccess eaBackground]#Early Access# -* `include_header` [earlyAccess eaBackground]#Early Access# - -Contact ThoughtSpot support to enable these settings for PNG downloads on your ThoughtSpot instance. +* `image_resolution` +* `image_scale` +* `include_header` [IMPORTANT] ==== diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 3d8d67eee..93c78c350 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -10,6 +10,90 @@ This page explains how to embed a ThoughtSpot Liveboard in your web page, portal A ThoughtSpot Liveboard is an interactive dashboard that presents a collection of visualizations pinned by a user. +// ============================================================ +// SOURCE: SCAL-309481, SCAL-292918, SCAL-295712, SCAL-312731 +// TODO: [WRITER] Review all four change notes in this section before publishing. +// Each TODO inline identifies a specific verification item. +// ============================================================ + +[#embed-pinboard-26-8] +== Changes in ThoughtSpot Cloud 26.8.0.cl [.version-badge.new]#New# + +=== WYSIWYG Liveboard PDF export +// SOURCE: SCAL-309481 +// TODO: [WRITER] Confirm with the SDK team whether Action.DownloadAsPdf behavior changes in 26.8.0.cl — specifically whether a new Action enum is introduced for the legacy PDF format. +// TODO: [WRITER] Confirm whether `enableV2Shell: true` is still required for the new PDF experience or is now the default in 26.8.0.cl. + +Starting from ThoughtSpot Cloud 26.8.0.cl, the WYSIWYG Liveboard PDF export experience is generally available (GA) for all users, including embedded deployments. The new PDF export renders the Liveboard exactly as it appears on screen — layout, filters, chart styles, and tab structure included. + +*Impact on embedded applications:* + +* `Action.DownloadAsPdf` — No code changes required. The WYSIWYG PDF experience is applied automatically on upgrade. +* If your application suppresses or customizes the PDF download action using `disabledActions` or `hiddenActions`, verify that behavior is unchanged after the upgrade. + +[source,JavaScript] +---- +// Example: suppress PDF download in an embedded Liveboard +const embed = new LiveboardEmbed('#embed', { + liveboardId: '<%=liveboardGUID%>', + disabledActions: [Action.DownloadAsPdf], + disabledActionReason: 'PDF export is disabled in this view.', +}); +---- + +=== Discoverability removed — explicit sharing required +// SOURCE: SCAL-292918 +// TODO: [WRITER] Confirm whether any REST API endpoint related to Liveboard sharing is affected by this change. Add a cross-reference to the REST API changelog if so. +// TODO: [WRITER] Confirm with the product team what the recommended migration path is for customers who relied on discoverability to distribute embedded content. + +The *Make this Liveboard discoverable* option has been removed in ThoughtSpot Cloud 26.8.0.cl. Liveboards are no longer discoverable by default — access is granted exclusively through explicit sharing. This is a backend behavior change; no SDK code changes are required. + +*Impact on embedded applications:* + +* Embedded users who previously relied on Liveboard discoverability to find shared content must now receive explicit sharing access from a ThoughtSpot administrator or Liveboard owner. +* Embedded applications that manage sharing programmatically via the REST API are not affected. + +=== TSE GA defaults — Compact Header, Hide Irrelevant Filters, Cover Filter Panel, Aether +// SOURCE: SCAL-295712 +// TODO: [WRITER] Confirm the exact list of features defaulted to GA in TSE for 26.8.0.cl with the TSE/product team (Navan Phase 1, Aether, Cover Filter Panel, Compact Header, Hide Irrelevant Filters). +// TODO: [WRITER] Confirm whether any feature requires an explicit opt-out flag if an embedded application relied on the previous non-default behavior. If so, document the opt-out property and its value. + +The following features are now generally available (GA) and enabled by default for all ThoughtSpot embedded deployments in 26.8.0.cl: + +[width="100%", cols="3,6"] +[options="header"] +|==== +|Feature |Description +|Compact Header |Renders a compact, space-efficient Liveboard header. Previously required explicit opt-in. +|Hide Irrelevant Filters |Automatically hides filters that are not applicable to the current Liveboard tab. +|Cover Filter Panel |Shows the filter panel as an overlay instead of inline. +|Aether UI |Updated ThoughtSpot Aether design system applied to embedded Liveboards. +// TODO: [WRITER] Confirm "Aether UI" is the correct product name for this feature. Verify with the design/product team. +|==== + +=== Navigation V3 is now the default +// SOURCE: SCAL-312731 +// TODO: [WRITER] Confirm the exact release in which Navigation V1 and V2 will be fully removed (not just deprecated). +// TODO: [WRITER] Confirm whether passing `navVersion: 'V1'` or `'V2'` in AppEmbed silently falls back to V3 or throws a console error in 26.8.0.cl. + +Starting from ThoughtSpot Cloud 26.8.0.cl, Navigation V3 is the default navigation experience for all embedded deployments. Navigation V1 and V2 are deprecated and will be removed in a future release. + +If your application explicitly sets `navVersion` to `V1` or `V2`, update your configuration: + +[source,JavaScript] +---- +// Deprecated — remove navVersion property in 26.8.0.cl +// navVersion: 'V2', + +// V3 is now the default — no explicit setting required +const embed = new AppEmbed('#embed', { + pageId: Page.Home, + // navVersion is no longer required; V3 is applied automatically +}); +---- + +For more information, see xref:full-app-customize.adoc[Customize the full app experience]. + == Import the LiveboardEmbed package Import the `LiveboardEmbed` SDK library to your application environment: diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index eaaf2b1a0..01fbdf608 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -35,14 +35,13 @@ import { prefetch, EmbedEvent, HostEvent -} -from '@thoughtspot/visual-embed-sdk'; +} from '@thoughtspot/visual-embed-sdk'; ---- **ES6** [source,JavaScript] ---- - ---- == Initialize the SDK @@ -132,7 +131,6 @@ spotterEmbed.on(EmbedEvent.Subscribed, (eventData) => { }); ---- - To trigger actions on the embedded interface, use the xref:HostEvent.adoc[Host events]. The following example shows the host event to reset a Spotter conversation session: @@ -164,291 +162,7 @@ spotterEmbed.render(); [#configControls] == Customizing the embedded Spotter interface -When you embed Spotter, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding. - -=== Spotter Classic and Spotter 2 experiences -If you have embedded Spotter Classic or Spotter 2, the initial page includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session. - -[.widthAuto] -[.bordered] -image::./images/spotter-embed-legacy.png[Spotter embed] - -=== Spotter 3 experience -In Spotter 3 embedding, you can load the page with a pre-selected data source or use the *Auto mode* to allow Spotter to automatically discover and select a relevant data model for user queries. - -**Default view**: - -[.widthAuto] -[.bordered] -image::./images/spotter3-legacy-interface.png[Spotter 3 interface] - -**With Auto mode enabled**: - -[.widthAuto] -[.bordered] -image::./images/spotter3-leagcy-interface-automode.png[Spotter 3 interface] - -[NOTE] -==== -When Auto mode is enabled, **Preview data** and **Data Model instructions** options will not be available. -==== - - -==== New chat interface - -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: - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed configuration attributes - // Enable the updated Spotter chat prompt experience. - updatedSpotterChatPrompt: true, -}); ----- - -[.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'), { - // ... - 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 - }, -}); ----- - -[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. - -[#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. - -[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, - SpotterEmbedViewConfig, - SpotterChatViewConfig -} 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. - -[source,JavaScript] ----- -const embed = spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - //... - spotterChatConfig: { - spotterFileUploadEnabled: true, - spotterFileUploadFileTypes: { types: ['pdf', 'png', 'xlsx'] - }, -}); ----- - -[#spotterMenuActions] -=== Customizing menu actions and elements - -The SDK provides action IDs to disable, show, or hide the following elements and menu actions via `disabledActions`, `visibleActions`, or `hiddenActions` arrays. - -For example, you can hide the *Preview data*, *Reset* in the prompt panel, or *Pin*, *Download*, and other actions from a Spotter-generated response. - -The following code sample disables actions and menu elements using the xref:embed-actions.adoc[`disabledActions`] array: - -[source,JavaScript] ----- - // 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]. - +When you embed Spotter, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding. To learn about the customization options available with the Visual Embed SDK, see xref:customize-spotter-embed.adoc[Customizing the Spotter embed view]. == Code samples @@ -465,8 +179,7 @@ import { 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({ diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index 9c74008b6..88bd82873 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 diff --git a/modules/ROOT/pages/embed-ts-react-app.adoc b/modules/ROOT/pages/embed-ts-react-app.adoc index 22f191e43..2c75f3ed8 100644 --- a/modules/ROOT/pages/embed-ts-react-app.adoc +++ b/modules/ROOT/pages/embed-ts-react-app.adoc @@ -14,7 +14,12 @@ Before embedding ThoughtSpot, perform the following checks: === Prepare your environment +* Check if link:https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[NPM and Node.js are installed, window=_blank] in your setup. Any link:https://nodejs.org/en/about/previous-releases[active LTS release, window=_blank] of Node.js is recommended for build tooling. +* Make sure you have installed React 16.8 or later and its dependencies. The SDK declares React and React DOM as peer dependencies at version 16.8 or later. If React is not installed, open a terminal window and run the following command: + * Check if link:https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[NPM and Node.js are installed, window=_blank] in your setup. + + * Make sure you have installed React framework and its dependencies. If React is not installed, open a terminal window and run the following command: + ---- diff --git a/modules/ROOT/pages/events-hostEvents.adoc b/modules/ROOT/pages/events-hostEvents.adoc index b397dec92..732726929 100644 --- a/modules/ROOT/pages/events-hostEvents.adoc +++ b/modules/ROOT/pages/events-hostEvents.adoc @@ -7,9 +7,9 @@ :page-description: Events allow the host application to trigger actions in or payloads from the embedded ThoughtSpot components. [#host-events] -Host events provide programmatic entry points to actions that your host or embedding application can trigger into the embedded ThoughtSpot iframe to perform the same operations a user can perform in the UI, such as opening filters, editing, saving, pinning, drilling, or navigating to an answer. +Host events provide programmatic entry points to actions that your host or embedding application can trigger in the embedded ThoughtSpot iframe to perform the same operations a user can perform in the UI, such as opening filters, editing, saving, pinning, drilling, or navigating to an answer. -Host events use the `.trigger()` method to send the event message to embedded ThoughtSpot components in the `.trigger(hostEvent, data)` format. The host events are part of the *HostEvent* object; for example, `HostEvent.SetVisibleTabs`. +Host events use the `.trigger()` method to send the event message to embedded ThoughtSpot components in the `.trigger(hostEvent, data)` format. The host events are part of the `HostEvent` object; for example, `HostEvent.SetVisibleTabs`. == Event categories @@ -24,7 +24,7 @@ Host events can be categorized based on their schema and what they do: == Configuring host events -To configure a host event, use the `.trigger()`. +To configure a host event, use the `.trigger()` method. The following example uses `HostEvent.SetVisibleTabs` to show specific tabs whose IDs are specified in the payload. Any tabs whose IDs are not included in this array are hidden. @@ -47,7 +47,7 @@ In your host events implementation, you can choose to trigger an action without ==== Parameters for HostEvent.Pin -The *Pin* action is available on the charts and tables generated from a search query, saved Answers, and visualizations on a Liveboard. Generally, when a user initiates the pin action, the *Pin to Liveboard* modal opens, and the user is prompted to specify the Liveboard to pin the object. The modal also allows the user to add or edit the title text of the visualization and create a new Liveboard if required. +The *Pin* action is available on the charts and tables generated from a search query, saved Answers, and visualizations on a Liveboard. Generally, when a user initiates the pin action, the *Pin to Liveboard* modal opens, and the user is prompted to specify the Liveboard to pin the object to. The modal also allows the user to add or edit the title text of the visualization and create a new Liveboard if required. With `HostEvent.Pin`, you can automate the pin workflow to programmatically add an Answer or visualization to a Liveboard. For example, to pin an object to an existing Liveboard, use the following parameters in the host event object: @@ -56,15 +56,13 @@ __String__. GUID of the saved Answer or visualization to pin to a Liveboard. Not * `liveboardId` + __String__. GUID of the Liveboard to pin the Answer. If there is no Liveboard, you must specify the `newLiveboardName` to create a new Liveboard. * `newVizName` + -__String__. Name string for the Answer that will be added as a visualization to the Liveboard. Note that each time the user clicks, a new visualization object with a new GUID is generated. +__String__. Name string for the visualization. When specified, it adds a new visualization or creates a copy of the Answer or visualization specified in `vizId`. Note that each time this event is triggered, a new visualization object with a new GUID is generated. * `tabId` + __String__. GUID of the Liveboard tab. Adds the Answer to the Liveboard tab specified in the code. -* `newLiveboardName` +* `newLiveboardName` + __String__. Name string for the new Liveboard. Creates a new Liveboard object with the specified name. * `newTabName` + __String__. Name string for the new Liveboard tab. Adds a new tab to the Liveboard specified in the code. -* `newVizName` + -__String__. Name string for the visualization. When specified, it adds a new visualization or creates a copy of the Answer or visualization specified in `vizId`. In this example, when the `HostEvent.Pin` is triggered, the *Pin* action is initiated to add a specific visualization to a specific Liveboard tab: @@ -83,12 +81,12 @@ In this example, when the `HostEvent.Pin` is triggered, the *Pin* action is init [source,JavaScript] ---- const pinResponse = await searchEmbed.trigger(HostEvent.Pin, { - newVizName: `Sales by region`, + newVizName: "Sales by region", liveboardId: "5eb4f5bd-9017-4b87-bf9b-8d2bc9157a5b", }) ---- -In this example, when the `HostEvent.Pin` is triggered, the *Pin* action is initiated to create a new Liveboard with a tab, and then pin the Answer or visualization to it. +In this example, when the `HostEvent.Pin` is triggered, the *Pin* action is initiated to create a new Liveboard with a tab, and then pin the Answer or visualization to it: [source,JavaScript] ---- @@ -113,7 +111,7 @@ For `HostEvent.SaveAnswer`, you can pass the pre-defined attributes such as name * `name` + __String__. Name string for the Answer object. * `description` + -__String__. Description text for the Answer +__String__. Description text for the Answer. [source,JavaScript] ---- @@ -130,19 +128,67 @@ If `HostEvent.SaveAnswer` does not include any parameters, the event triggers th searchEmbed.trigger(HostEvent.SaveAnswer); ---- - === Retrieving and updating filters - The SDK provides the following events for filter retrieval and updates: -* `HostEvent.GetFilters` to get the filters that are currently applied on an embedded Liveboard. You can use this event to inspect the current filter state or to retrieve filter values. -* `HostEvent.UpdateFilters` to update the filters applied on an embedded Liveboard. -* `HostEvent.OpenFilter` to open the filter panel for the specified column. -* `HostEvent.UpdateRuntimeFilters` to update xref:runtime-filters.adoc[Runtime filters]. + -Runtime filters are applied at runtime, that is, when loading the embedded ThoughtSpot content. Runtime filters can also be updated after the load time using `HostEvent.UpdateRuntimeFilters`. You can add a UI option or button in your embedding app and assign the `HostEvent.UpdateRuntimeFilters` to trigger the `UpdateRuntimeFilters` event when that button is clicked. -+ +==== HostEvent.GetFilters +You can use this event to inspect the current filter state or to retrieve filter values. The `HostEvent.GetFilters` returns an array of filter objects representing the filters currently applied on the embedded Liveboard. Each filter object includes the following additional properties: + +`applicable_viz`:: +An object describing which visualizations on the Liveboard this filter applies to. Includes the following properties: + +* `type`. __String__. Scope of the filter. + +** `ALL` means the filter applies to all visualizations. + +** `SPECIFIC` means the filter applies only to the visualization IDs listed in `viz_ids`. +* `viz_ids`. __Array of strings__. Array of visualization GUIDs to which the filter applies. Populated only when `type` is `SPECIFIC`. + +`linking`:: +An object describing the filter-linking state of this filter. Includes the following properties: + +* `is_linked`. __Boolean__. Is `true` if this filter is linked to other filters on the Liveboard. +* `linked_columns`. __Array of strings__. Array of column names or GUIDs that this filter is linked to. + +[source,JSON] +---- +[ + { + "column": "Region", + "operator": "EQ", + "values": ["West"], + "applicable_viz": { + "type": "SPECIFIC", + "viz_ids": ["viz-guid-1", "viz-guid-2"] + }, + "linking": { + "is_linked": true, + "linked_columns": ["Country"] + } + }, + { + "column": "Date", + "operator": "BW_INC", + "values": ["2024-01-01", "2024-12-31"], + "applicable_viz": { + "type": "ALL", + "viz_ids": [] + }, + "linking": { + "is_linked": false, + "linked_columns": [] + } + } +] +---- + +==== HostEvent.UpdateFilters +Updates the filters applied on an embedded Liveboard. For more information and examples, see xref:HostEvent.adoc#_updatefilters[HostEvent reference documentation]. + +==== HostEvent.OpenFilter +Opens the filter panel for the specified column. For more information and examples, see xref:HostEvent.adoc#_openfilter[HostEvent reference documentation]. + +==== HostEvent.UpdateRuntimeFilters +xref:runtime-filters.adoc[Runtime filters] are applied at runtime, that is, when loading the embedded ThoughtSpot content. Runtime filters can also be updated after the load time using `HostEvent.UpdateRuntimeFilters`. You can add a UI option or button in your embedding app and assign `HostEvent.UpdateRuntimeFilters` to a button to trigger the event when that button is clicked. + In this example, the host event is assigned to a button that updates runtime filters when clicked. When `HostEvent.UpdateRuntimeFilters` is triggered, the filters are updated with the attributes specified in the code. -+ + [source,JavaScript] ---- document.getElementById('updateFilters').addEventListener('click', e => { @@ -163,12 +209,12 @@ In this example, the host event is assigned to a button that updates runtime fil === Filtering from the selection Filtering from a selection on a chart or table can be implemented by combining the `EmbedEvent.VizPointClick` or `EmbedEvent.VizPointDoubleClick` events with the `HostEvent.UpdateRuntimeFilters` event. -The callback function from the `VizPointClick` event will need to read the response, parse out the attributes from the response that will be sent to the Runtime Filters object, and then send the attributes and their target fields in the format used by `UpdateRuntimeFilters`. +The callback function from the `VizPointClick` event will need to read the response, parse out the attributes from the response that will be sent to the Runtime Filters object, and then send the attributes and their target fields in the format used by `HostEvent.UpdateRuntimeFilters`. === Using vizId to target a specific visualization If a host event allows the `vizId` parameter, you can use it to target a specific visualization where applicable. For example, to trigger the *Edit* action on a specific visualization in an embedded Liveboard, you can specify the `vizId` parameter in the host event payload. -In the following example, the host event triggers the **Edit** action on the specified visualization in a Liveboard embed: +In the following example, the host event triggers the *Edit* action on the specified visualization in a Liveboard embed: [source,JavaScript] ---- @@ -181,7 +227,7 @@ liveboardEmbed.trigger(HostEvent.Edit, { }); ---- -If `vizId` is not specified, the edit action is triggered at the Liveboard level, instead of the visualization layer. +If `vizId` is not specified, the *Edit* action is triggered at the Liveboard level, instead of the visualization layer. In Spotter embed, `vizId` is a required parameter for several host events. If it is not specified in the host event, the event trigger fails and results in an error indicating that the visualization context is missing. @@ -192,7 +238,7 @@ In the above example, if the visualization with the `730496d6-6903-4601-937e-2c6 == Host event behavior in single-layer and multi-layer UI scenarios -In single‑layer UI, such as a single visualization embed, Spotter embed, or Liveboards listing page in full application embed, a host event call typically results in a single visible action. However, in multi-modal or multi-layer UI, such as Spotter on Liveboard embed, a visualization opened from a Liveboard, or any experience with dialogs on top of a base page, a host event call can trigger multiple handlers at once. For example, the `HostEvent.OpenFilter` can open filters on both the visualization page in the overlay and the underlying Liveboard. +In single-layer UI, such as a single visualization embed, Spotter embed, or Liveboards listing page in full application embed, a host event call typically results in a single visible action. However, in multi-modal or multi-layer UI, such as Spotter on Liveboard embed, a visualization opened from a Liveboard, or any experience with dialogs on top of a base page, a host event call can trigger multiple handlers at once. For example, the `HostEvent.OpenFilter` can open filters on both the visualization page in the overlay and the underlying Liveboard. For context-aware routing and per‑context payload validation, we recommend using the host events framework with page context. For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. @@ -251,7 +297,6 @@ video::./images/hostEvent.mp4[width=100%,options="autoplay,loop"] ++++ Try it out in Playground - ++++ == Event enumerations and examples diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index d0659c9bb..d4c0d9849 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -35,7 +35,7 @@ xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more i 4. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters[Liveboard filters, window=_blank] + Liveboard filters apply to all visualizations on the Liveboard and are visible as UI components at the top of a Liveboard page. When a filter is clicked, a modal with filter options appropriate for the data type is displayed. + -Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using the `HostEvent.UpdateFilters`. +Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using `HostEvent.UpdateFilters`. 5. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters-cross[Liveboard cross filters, window=_blank] + Cross filters are ad-hoc filters based on user selection. These filters are used for brushing and linking Liveboard visualizations. + @@ -55,7 +55,7 @@ All operations result in a `WHERE` clause being applied to the queries generated A data filter object in ThoughtSpot typically includes the following attributes: `column`, `columnName`, **or** `columnId`:: -The name of the column to filter on. For example, `item type` or `product`. The column value must match the actual column name in the ThoughtSpot model. If the model uses column aliases, use the base column name, not the alias. This attribute is defined as `col1`, `col2`, `col3` in the object URLs and REST API requests, as `columnName` in the `runtimeFilters` array in the Visual Embed SDK. The filter object for host events in the SDK allows `column` or `columnName`. +The name of the column to filter on. For example, `item type` or `product`. The column value must match the actual column name in the ThoughtSpot model. If the model uses column aliases, use the base column name, not the alias. This attribute is defined as `col1`, `col2`, `col3` in the object URLs and REST API requests, and as `columnName` in the `runtimeFilters` array in the Visual Embed SDK. The filter object for host events in the SDK allows `column` or `columnName`. + If there are multiple columns with the same name, you can use the `WORKSHEET_NAME::COLUMN_NAME` format; for example, `"(Sample) Retail - Apparel::city"`. @@ -63,7 +63,7 @@ If there are multiple columns with the same name, you can use the `WORKSHEET_NAM The supported operators include: + [width="80%" cols="1,2,2"] -[options='header'] +[options="header"] |=== |Operator|Description|Number of Values @@ -122,6 +122,7 @@ The supported operators include: | `IN` | is included in this list of values | multiple + | `NOT_IN` | is not included in this list of values | multiple @@ -220,19 +221,38 @@ liveboardEmbed.trigger(HostEvent.UpdateFilters, { ---- === GetFilters and GetParameters events -If you want to build your own filter UI within the embedding app, you can find out details of the Liveboard and runtime filters that are defined using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getfilters[HostEvent.GetFilters]. There is an equivalent link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getparameters[HostEvent.GetParameters] to get the currently set Parameter values: +If you want to build your own filter UI within the embedding app, you can find out details of the Liveboard and runtime filters that are defined using `HostEvent.GetFilters`. + +**GetFilters** [source,JavaScript] ---- const data = await liveboardEmbed.trigger(HostEvent.GetFilters); console.log('data', data); +---- + +Each filter object in the `HostEvent.GetFilters` response includes two additional fields: + +* `applicable_viz`: indicates whether the filter applies to `ALL` visualizations or only `SPECIFIC` ones (with a `viz_ids` array). +* `linking`: indicates whether the filter is linked to other filters, and which columns it is linked to (`is_linked`, `linked_columns`). + +For more information, see xref:events-hostEvents.adoc#_hostevent_getfilters[HostEvent.GetFilters] and xref:HostEvent.adoc#_getfilters[HostEvent reference documentation]. + +**GetParameters** + +To get the currently set Parameter values, use `HostEvent.GetParameters`: + +[source,JavaScript] +---- liveboardEmbed.trigger(HostEvent.GetParameters).then((parameter) => { console.log('parameters', parameter); }); ---- -Note that `HostEvent.GetFilters` and `HostEvent.GetParameters` return a promise directly rather than taking a callback function as their second argument. +[NOTE] +==== +`HostEvent.GetFilters` and `HostEvent.GetParameters` return a promise directly rather than taking a callback function as their second argument. +==== === FilterChanged and ParameterChanged events You can also listen for the user's interactions with the filters using the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_filterchanged[EmbedEvent.FilterChanged]. @@ -267,7 +287,7 @@ When updating filters using `HostEvent.UpdateFilters`, you must include the date The following table lists the supported filter types and examples for each type: [width="100%" cols="3,8"] -[options='header'] +[options="header"] |===== |Type| Description @@ -460,7 +480,7 @@ The `override_filters` value is a JSON array of filter objects, with each object [IMPORTANT] ==== -* The `override_filters` accepts a JSON array directly, not an object that wraps the array. +* The `override_filters` parameter accepts a JSON array directly, not an object that wraps the array. * Specifying two or more filter objects that target the same date column returns the error, `more than one filter objects are not allowed for date type column `. However, columns with other data type do not have this restriction. Multiple filter objects on the same non-date column are merged. ==== @@ -508,6 +528,7 @@ Valid values for rolling date filters include: + * `TODAY` - The current calendar day. * `TOMORROW` - The next calendar day. * `THIS_PERIOD` - The current period (for example, this quarter). +* `LAST_PERIOD` - The previous single period (for example, last month). * `NEXT_PERIOD` - The next single period (for example, next month). * `LAST_N_PERIOD` - The last _N_ complete periods. * `NEXT_N_PERIOD` - The next _N_ complete periods. @@ -536,7 +557,7 @@ Valid values for `datePeriod` include: * `MONTH` - Calendar month * `QUARTER` - Calendar quarter * `YEAR` - Calendar year -* `HOUR` - Hour (`dateTime` columns only) +* `HOUR` - Hour (`datetime` columns only) * `MINUTE` - Minute (`datetime` columns only) * `SECOND` - Second (`datetime` columns only) @@ -675,7 +696,7 @@ Name of the month in uppercase. Required for `MONTH_YEAR`. Refer to the following table for examples of JSON object for date filters: [width="100%" cols="3,8"] -[options='header'] +[options="header"] |===== |Date filter type | Example @@ -917,4 +938,6 @@ Refer to the following documentation for more information: === Events There is no specific event to update `search_query filters` in the `SearchEmbed` component or the Liveboard edit mode. -You can set your app to listen to link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_querychanged[EmbedEvent.QueryChanged] and trigger the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_gettml[HostEvent.GetTML] event to get a new TML generated for the `search_query` string after an update. \ No newline at end of file +You can set your app to listen to link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_querychanged[EmbedEvent.QueryChanged] and trigger the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_gettml[HostEvent.GetTML] event to get a new TML generated for the `search_query` string after an update. + +//// \ No newline at end of file diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index b4e60b77e..aaa4b8978 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -1,67 +1,65 @@ -= Customize full application embedding += Customize the home page and navigation for full application embedding :toc: true :toclevels: 3 -:page-title: Customize full application embedding +:page-title: Customize the home page and navigation for full application embedding :page-pageid: full-app-customize -:page-description: Customize full application embedding +:page-description: Customize the home page and navigation for full application embedding -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. +ThoughtSpot supports the following experience modes in full application embedding: + +* *V3 experience* (`HomePage.ModularWithStylingChanges`)—The default home page experience as of ThoughtSpot Cloud 26.8.0.cl. Includes the left navigation panel, customizable modules, and styling changes. +* *V4 experience* (`HomePage.Focused`)—An enhanced home page experience with a focused layout and additional customization options. [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. +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. ==== -== 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__) - -The key differences between these UI experience modes are listed in the following table: - -[div boxAuto] --- -[width="100%", cols="2,4,4,5"] -[options='header'] - -|===== -|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 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. + -Limited customization controls |Redesigned top navigation bar with an app selector and other icons + -Separate left navigation panel for each application context| Sliding left navigation panel with persona-based application icons + -A dynamic left navigation menu that adjusts its contents according to the application context. -|**Home page experience** | Static home page with limited customization control a| Modular home page with customizable components |Modular home page with customizable components, enhanced styling, and visual elements. - -[NOTE] -==== -The SDK also supports a V4 focused home page experience [earlyAccess eaBackground]#Early Access#. For more information, see xref:full-app-customize.adoc#_enable_the_v4_focused_home_page_experience[Enable the V4 focused home page experience]. -==== +== UI experience modes -|**Feature availability**| Enabled by default| Disabled by default | Disabled by default -|===== --- +ThoughtSpot supports V3 and V4 home page and navigation experiences for full application embedding. + +[width="100%", cols="5,^3,^3"] +[options="header"] +|==== +|Feature |V3 experience + +`HomePage.ModularWithStylingChanges` |V4 experience + +`HomePage.Focused` +|Default experience as of 26.8.0.cl +|[tag greenBackground tick]#✓# Default +|[tag redBackground tick]#x# Not default +|`hideHomepageLeftNav` + +Hides the left navigation panel on the home page. +|[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported +|`hiddenHomepageModules` + +Hides specific modules on the home page. +|[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported +|`reorderedHomepageModules` + +Reorders modules on the home page. +|[tag greenBackground tick]#✓# Supported +|[tag redBackground tick]#x# Not supported +|`homePageModules` + +Specifies which modules to show on the home page. +|[tag greenBackground tick]#✓# Supported +|[tag redBackground tick]#x# Not supported +|Left navigation panel customization +|[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported +|Custom reordering of left nav items +|[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported +|==== **V3 navigation and home page experience** [.bordered] [.widthAuto] image::./images/v3-experience.png[V3 UI experience] -**V2 navigation and home page experience** -[.bordered] -[.widthAuto] -image::./images/v2-experience.png[V2 UI experience] - -**V1 Classic experience** +**Classic (V1) navigation and home page experience** [.bordered] [.widthAuto] image::./images/v1-experience.png[Classic experience] @@ -94,70 +92,13 @@ Enables the modular or focused home page experience. Valid values include: Enables the V3 modular home page experience. You must include `primaryNavbarVersion` to update the UI experience to the V3 home page. ** `HomePage.Focused` [earlyAccess eaBackground]#Early Access# Enables the V4 focused home page experience, which consolidates the **Watchlist** and **Recents** sections into a single, focused view. + -** `HomePage.Modular` + -Enables the modular home page experience with customizable components. This experience does not include the styling options and visual changes available with the full V3 experience. We do not recommend using this option, as it will be deprecated in an upcoming release. - - -[IMPORTANT] -==== -* To enable the full V3 experience, both `primaryNavbarVersion` and `homePage` attributes must be set in the SDK. Not setting `primaryNavbarVersion` will result in no changes to the UI experience. -* If you include only the `homePage: HomePage.ModularWithStylingChanges` attribute in `discoveryExperience`, it will be ignored. + -* If you include only the homePage attribute with its value as `HomePage.Modular`, the V2 modular home page experience will be enabled. - -For information about these configuration combinations and their effects, see xref:full-app-customize.adoc#_ui_customization_options_and_resulting_experience[UI customization options and resulting experience]. -==== - -==== Upgrade from classic (V1) experience to V3 experience -To enable the V3 experience, set the `primaryNavbarVersion` and `homePage` parameters in the `discoveryExperience` object as shown in the following example. - -Note that these attributes use the values from the xref:PrimaryNavbarVersion.adoc[PrimaryNavbarVersion] and xref:HomePage.adoc[HomePage] enumerations. - -[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 - homePage: HomePage.ModularWithStylingChanges, // Enable V3 home page experience - }, - // Show navigation panels - showPrimaryNavbar: true, - //... other embed view configuration attributes -}); ----- - -==== 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'; +** `HomePage.Modular` + +Enables the modular home page experience with customizable components. This experience does not include the styling options and visual changes available with the full V3 experience. We do not recommend using this option, as it will be deprecated in an upcoming release. +//// -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 @@ -181,56 +122,27 @@ import { } 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 + 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 +==== Post upgrade 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 whether the UI shows the new navigation and home page by default. * 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: @@ -352,7 +264,7 @@ a|`false` | V3 navigation and V4 home page experience |=== -- - +//// == Customize navigation experience @@ -368,9 +280,9 @@ In full application embedding, the home page is set as the default landing page 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. +If your embed has the V3 navigation and homepage experience enabled, the ListPage V3 experience is 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: +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. @@ -398,7 +310,8 @@ const embed = new AppEmbed("#embed", { // hide Author, Share, and Tags columns on Answers and Liveboards listing pages hiddenListColumns: [ ListPageColumns.Author, - ListPageColumns.Share + ListPageColumns.Share, + ListPageColumns.Tags ], //... other view config attributes @@ -413,7 +326,7 @@ The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but d == 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. +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] ---- @@ -427,7 +340,6 @@ An example of using direct selectors in a file is available in the link:https:// 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] @@ -436,4 +348,9 @@ You can also declare direct selectors using the xref:css-customization.adoc#_css * xref:HostEvent.adoc[Host events] * xref:EmbedEvent.adoc[Embed Events] +== Related resources +* xref:customize-nav-full-embed.adoc[Customize the navigation for full application embedding] +* xref:customize-homepage-full-embed.adoc[Customize the home page for full application embedding] +* xref:full-embed.adoc[Embed full application] +* link:https://developers.thoughtspot.com/docs/typedoc/interfaces/AppViewConfig.html[AppViewConfig reference, window=_blank] \ No newline at end of file diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc index 803f62516..2a9165058 100644 --- a/modules/ROOT/pages/getting-started.adoc +++ b/modules/ROOT/pages/getting-started.adoc @@ -208,7 +208,15 @@ lb.trigger(HostEvent.UpdateRuntimeFilters, [{ `#container` is a selector for the DOM node which the code assumes is already attached to DOM. The SDK will render the ThoughtSpot component inside this container element. == Embed in a React app -ThoughtSpot provides React components for embedding Search, Liveboard, and the full ThoughtSpot application in a React app. The following code sample shows how to embed a Liveboard component in a React app: +ThoughtSpot provides React components for embedding Search, Liveboard, and the full ThoughtSpot application in a React app. + +[NOTE] +==== +If you are embedding ThoughtSpot using the React components (`@thoughtspot/visual-embed-sdk/react`), React 16.8 or later and React DOM are required as peer dependencies in your project. + +For information about React version support, see link:https://react.dev/versions[React releases, window=_blank]. +==== + +The following code sample shows how to embed a Liveboard component in a React app: [source,TypeScript] ---- diff --git a/modules/ROOT/pages/input-tables-api.adoc b/modules/ROOT/pages/input-tables-api.adoc new file mode 100644 index 000000000..12fe8437b --- /dev/null +++ b/modules/ROOT/pages/input-tables-api.adoc @@ -0,0 +1,203 @@ += Input Tables API reference +:toc: true +:toclevels: 2 + +:page-title: Input Tables API +:page-pageid: input-tables-api +:page-description: Use the Input Tables REST API v2.0 endpoints to create, update, and delete input table records in ThoughtSpot programmatically. +:keywords: input tables, REST API, create input table, update input table, delete input table, writable tables +:product-version: 26.8.0.cl +:jira-ref: SCAL-319440 + +// SOURCE: SCAL-319440 | ThoughtSpot Cloud 26.8.0.cl +// TODO: [WRITER] Confirm the Jira key for the Input Tables REST API feature — SCAL-319440 is the +// best match found at time of authoring. Verify with the Data platform / DM team. +// TODO: [WRITER] Confirm whether Input Tables require a specific license or feature flag to be +// enabled on the ThoughtSpot instance before these APIs are available. +// TODO: [WRITER] Confirm whether `input_table_identifier` accepts both the GUID and the table +// name, or only one of these. Verify with the platform team. +// TODO: [WRITER] Confirm the required privilege name for input table write operations. +// "Can manage data" is assumed — verify with the access control team. +// TODO: [WRITER] Add a conceptual overview link once an Input Tables concept page exists. +// TODO: [WRITER] Request confirmed example payloads from the Data platform team to replace +// the illustrative examples in this page before publishing. + +ThoughtSpot introduces REST API v2.0 endpoints for managing input table records +programmatically. Input tables are writable tables in ThoughtSpot that allow you to push +data directly into ThoughtSpot without an external data pipeline. Use these APIs to create +new input tables, insert or update records, and delete records at scale. + + +== Supported operations + +* <> — `POST /api/rest/2.0/input-tables/create` +* <> — `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` +* <> — `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` + +=== Required permissions + +// TODO: [WRITER] Confirm the exact privilege required. "Can manage data" is assumed. +To use Input Tables API endpoints, `DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege is required. If Role-Based Access Control (RBAC) is enabled on your ThoughtSpot instance, the `CAN_MANAGE_INPUT_TABLES` (*Can manage input tables*) privilege is required. + +// ───────────────────────────────────────────────────────────────────────────────────────── +[#create-input-table] +== Create an input table + +Creates an input table and links it to a ThoughtSpot model (worksheet). An input table is a user-editable table stored in the model's external Cloud Data Warehouse (CDW) connection. It lets analysts enter or import data directly from the ThoughtSpot UI without requiring access to the underlying warehouse. + +=== Resource URL + +---- +POST /api/rest/2.0/input-tables/create +---- + +=== Request parameters + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description + +|`table_name` +|string +|Yes +|Name of the input table to create. Must be unique within the Org. + +|`table_definition` +|array of objects +|Yes +a|Describes the table schema. Each object requires: + + +* `referenced_columns` - List of column GUIDs from the linked model to include as read-only reference columns in the input table. These columns anchor the input data to existing model dimensions. + +* `name` (string) — Column display name. + +* `data_type` (string) — Warehouse data type. For example, `VARCHAR`, `INT64`, `DATE`, `BOOL`. + +* `type` (string) — Semantic role of the column: `ATTRIBUTE` for dimension columns or `MEASURE` for numeric columns. + + +|`model_identifier` +|string +|Yes +|GUID or name of the Model to link the input table to. + +|=== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/create' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + -H 'Content-Type: application/json' \ + -d '{ + "table_name": "table_name4", + "model_identifier": "model_identifier4", + "table_definition": { + "new_columns": [ + { + "name": "name2", + "data_type": "data_type0", + "type": "ATTRIBUTE" + } + ], + "referenced_columns": [ + "referenced_columns9" + ] + } +}' +---- + +=== Example response + +[source,JSON] +---- +{ + "input_table_identifier": "f47ac10b-58cc-4372-a567-0e02b2c3d479" +} +---- + + +// ───────────────────────────────────────────────────────────────────────────────────────── +[#update-input-table] +== Update records in an input table + +Writes rows of data into an existing input table. The supplied rows replace the current contents of the table. Partial updates to individual rows are not supported; re-submit all rows on every write. + +=== Resource URL + +---- +POST /api/rest/2.0/input-tables/{input_table_identifier}/update +---- +=== Request parameters + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description +|`input_table_identifier` |string |Yes |GUID or name of the input table to update. Pass the input table GUID as the path parameter in the API request. +|`rows` |array of objects |Yes |Rows to insert or update. Each object maps column name to value. Column names must match the table schema. +|=== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/f47ac10b-58cc-4372-a567-0e02b2c3d479/update' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + -H 'Content-Type: application/json' \ + -d '{ + "columns": ["region", "target_revenue", "effective_date"], + "rows": [ + ["West", "1500000", "2025-01-01"], + ["East", "2000000", "2025-01-01"] + ] + }' +---- + +=== Example response + +[source,JSON] +---- +{ + "rows_loaded": 2 +} +---- + +// ───────────────────────────────────────────────────────────────────────────────────────── +[#delete-input-table] +== Delete an input table + +This operation unlinks the input table from its Model, removes it from the connection metadata, and drops the physical table from the Cloud Data Warehouse. + +Deleting an input table does not delete the linked model. However, any Answers or Liveboards that reference columns from the deleted input table will lose access to that data and may return errors until the affected visualizations are updated. + +=== Resource URL + +---- +POST /api/rest/2.0/input-tables/{input_table_identifier}/delete +---- + +=== Request parameters + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description +|`input_table_identifier` |string |Yes |GUID or name of the input table. Pass the input table GUID as the path parameter in the API request. +|=== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/f47ac10b-58cc-4372-a567-0e02b2c3d479/delete' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + +---- + +=== Example response +A successful deletion returns the 204 response code. + +== Additional resources + +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] + diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index d011048de..abb14bda8 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -39,15 +39,15 @@ a| [discrete] ==== Org switching tools -Multi-Org users can now list their accessible Orgs and switch between them mid-session without logging out or re-authenticating. The following MCP tools are available exclusively on OAuth MCP Server endpoints, for authenticated users with multi-Org membership. +The OAuth MCP Server endpoints support the following MCP tools to discover the user's current Org and allow multi-Org users to switch to another Org mid-session without logging out or re-authenticating. -* `list_orgs`: Returns the Orgs your ThoughtSpot account currently has active membership in and the currently logged-in Org. +* `list_orgs`: Returns a list of the Orgs that the ThoughtSpot account is currently an active member of, along with the Org used for the user session. * `switch_org`: Switches the active Org for the current session. For more information, see xref:mcp-tool-reference-spotter3.adoc#org-switching-tools[Org switching tools]. [IMPORTANT] -The Org switching tools are not available on Bearer-token connections and user accounts with single-Org access. +The Org switching MCP tools are not available on Bearer-token connections. |==== 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] diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc index 17ea64d42..b2a21dbd5 100644 --- a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -17,9 +17,9 @@ Poll for streamed responses. * <> + Create a dashboard from session answers. * <> + -List the Orgs your account can access. (OAuth connections and multi-Org accounts only) +List the Orgs your account can access. (OAuth connections on Org-enabled instances only) * <> + -Switch your active Org for the current session. (OAuth connections and multi-Org accounts only) +Switch your active Org for the current session. (OAuth connections on Org-enabled instances only) * <> + Verify that the MCP Server is reachable. @@ -380,7 +380,7 @@ The following features are not supported directly. However, you can use the *Mak [#org-switching-tools] == Org switching tools -Some ThoughtSpot deployments use Orgs, the isolated tenant workspaces within a single instance, each with its own users, data models, and resources. A user may have membership in one or several Orgs and want to analyze data from a different Org without ending the session, closing the connection, or re-authenticating. When connecting to the MCP Server over OAuth, users with multi-Org access can discover and switch between Orgs during a session `list_orgs` and `switch_org` . +Some ThoughtSpot deployments use Orgs, the isolated tenant workspaces within a single instance, each with its own users, data models, and resources. A user may have membership in one or several Orgs and want to analyze data from a different Org without ending the session, closing the connection, or re-authenticating. When connecting to the MCP Server over OAuth on an Org-enabled instance, users can discover and switch between Orgs during a session using `list_orgs` and `switch_org`. Org switching is a two-step pattern: @@ -509,7 +509,9 @@ call_mcp_tool( === Known limitations * Signing in currently relies on a browser cookie from your ThoughtSpot cluster. If your browser blocks third-party cookies, the connection may fail to complete. -* Occasional re-authentication. Your connection is designed to stay active for up to 30 days. In rare cases, for example, if your ThoughtSpot instance is temporarily unreachable when your session token renews, you may be signed out and prompted to reconnect. If this occurs, reconnect the connector to restore access. +* Re-authentication is required in the following scenarios: +** If connection remains idle for 14 days, the session expires and requires reauthentication. +** If your ThoughtSpot instance is temporarily unreachable when your session token renews, you may be signed out and prompted to reconnect. [#check_connectivity] == check_connectivity diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index 92512748e..e4285cb47 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -281,6 +281,7 @@ Note the recommendation of Java SDK: [options='header'] |==== |ThoughtSpot release version|Supported SDK version +a|ThoughtSpot Cloud: 26.8.0.cl | v2.27.0 or later a|ThoughtSpot Cloud: 26.7.0.cl | v2.26.0 or later a|ThoughtSpot Cloud: 26.6.0.cl | v2.25.0 or later a|ThoughtSpot Cloud: 26.5.0.cl | v2.24.0 or later diff --git a/modules/ROOT/pages/rest-api-python-sdk.adoc b/modules/ROOT/pages/rest-api-python-sdk.adoc new file mode 100644 index 000000000..b5c5ddab6 --- /dev/null +++ b/modules/ROOT/pages/rest-api-python-sdk.adoc @@ -0,0 +1,378 @@ += Python SDK for REST API v2.0 +:toc: true +:toclevels: 3 + +:page-title: Python SDK for REST API v2.0 +:page-pageid: python-sdk +:page-description: Use the ThoughtSpot Python SDK to integrate REST API v2.0 in Python applications. The SDK is an async-first, fully-typed client generated from the ThoughtSpot OpenAPI specification. + +The ThoughtSpot Python SDK is an async-first, fully-typed client generated from the ThoughtSpot REST API v2.0 OpenAPI specification. It wraps every endpoint into a typed Python method and supports both asynchronous and synchronous invocation, transparent token refresh, server-sent event (SSE) streaming, file uploads and downloads, and typed exception handling. + +The Python SDK version 2.26.0 is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. + +== Prerequisites +Before you begin, ensure that: + +* Your environment is using Python 3.9 or later +* You have a valid ThoughtSpot user account with API access + +== Install the SDK + +Install the latest release from PyPI: + +[source,bash] +---- +pip install thoughtspot-rest-api-sdk +---- + +== Getting started +The ThoughtSpot Python SDK uses a single configuration field for bearer-token based authentication: `Configuration.access_token`. That field supports multiple input shapes, so you can start with a fixed token for simple use cases or use an automatic provider for production-grade token refresh. + +The SDK is async-first, but authentication works consistently across both async and synchronous SDK methods. When you supply a callable or the built-in token provider, the SDK resolves authentication at request time, so token refresh applies transparently to all API calls. + +=== Supported authentication options +The SDK supports a static token string, the built-in token provider, or your own callable token in `Configuration`. + +[width="100%",cols="1,2,3"] +[options="header"] +|==== +|Mode |When to use |How to configure + +|Static token |Use for short-lived scripts, testing purposes, or when your application already has a valid token. |Pass the bearer token string directly. + +|Custom callable |Custom identity provider or token store when your application fetches or refreshes tokens through its own identity flow. |Pass a sync or async function that returns a token string. + +|Built-in token provider a|Recommended in production environments when: + +* You are authenticating directly against ThoughtSpot +* You want the SDK to manage token refresh +* You want to avoid writing your own token lifecycle code. |Use `ThoughtSpotTokenProvider`. + +|==== + +=== Option 1: Static bearer token +Pass a bearer token string directly in the SDK configuration. + +[source,python] +---- +from thoughtspot_rest_api_sdk import Configuration, ThoughtSpotRestApi + +config = Configuration(host=BASE_URL, access_token="YOUR_BEARER_TOKEN") +---- + +In this mode, the SDK sends the token in the authorization header on each request. If the token expires, you must replace it manually. + +=== Option 2: Built-in token provider +The SDK includes a built-in `ThoughtSpotTokenProvider` for applications that require automatic token minting and refresh without writing their own token manager. + +This provider calls ThoughtSpot's `/auth/token/full` endpoint, caches the returned token until it nears expiry, and refreshes it automatically when needed. It also avoids redundant refreshes by collapsing concurrent refresh requests into a single token mint operation. + +For basic authentication, specify `password`: + +[source,python] +---- +from thoughtspot_rest_api_sdk import Configuration, ThoughtSpotRestApi, ThoughtSpotTokenProvider + +BASE_URL = "https://your-cluster.thoughtspot.cloud" # Replace with your ThoughtSpot cluster URL. + +# Basic authentication, supply password +provider = ThoughtSpotTokenProvider(BASE_URL, "USERNAME", password="PASSWORD") +config = Configuration(host=BASE_URL, access_token=provider) + +async with ThoughtSpotRestApi(configuration=config) as client: + user = await client.get_current_user_info() + print(user.name) +---- + +For trusted authentication, supply `secret_key`: + +[source,python] +---- +provider = ThoughtSpotTokenProvider(BASE_URL, "USERNAME", secret_key="YOUR_SECRET_KEY") +---- + +=== Option 3: Custom token callable +If your application already knows how to fetch or refresh tokens, you can pass a zero-argument function instead of a token string. The function can be synchronous or asynchronous, and the SDK invokes it for each request. + +[source,python] +---- +async def token_supplier() -> str: + return await my_identity_provider.fetch_bearer() + +config = Configuration(host=BASE_URL, access_token=token_supplier) +---- + +This pattern gives you full control over how tokens are sourced. For example, your callable can retrieve a token from an in-memory cache, an external identity provider, or a secrets-backed broker. + +== How to use +Create a `Configuration`, pass it to an `ApiClient`, and make calls through `ThoughtSpotRestApi` or a focused per-tag class such as `UsersApi` or `MetadataApi`. + +[source,python] +---- +import asyncio +from thoughtspot_rest_api_sdk import Configuration, ThoughtSpotRestApi + +BASE_URL = "https://your-cluster.thoughtspot.cloud" # Replace with your ThoughtSpot cluster URL. + +async def main(): + config = Configuration(host=BASE_URL, access_token="YOUR_BEARER_TOKEN") # Replace with a valid bearer token. + # Pass Configuration directly; the client manages its own connection pool. + # To share one pool across several API classes, build an ApiClient + # explicitly and pass that instead. See the Per-tag API classes section. + async with ThoughtSpotRestApi(configuration=config) as client: + + # Get current user + user = await client.get_current_user_info() + print(user.name) + + # Search with a request body (dict or the typed request model) + users = await client.search_users({"record_offset": 0, "record_size": 10}) + for u in users: + print(u.name) + +asyncio.run(main()) +---- + +=== Synchronous usage +Every async method has a blocking `*_sync` variant. No event loop or `await` is needed: + +[source,python] +---- +from thoughtspot_rest_api_sdk import Configuration, ThoughtSpotRestApi + +config = Configuration(host=BASE_URL, access_token="YOUR_BEARER_TOKEN") +client = ThoughtSpotRestApi(configuration=config) + +user = client.get_current_user_info_sync() +print(user.name) +---- +This makes the SDK usable from synchronous frameworks such as Django, Flask, scripts, and Jupyter notebooks. + +=== Per-tag API classes +`ThoughtSpotRestApi` exposes every endpoint on one class. For a focused surface, instantiate a per-tag class against a shared `ApiClient`. All classes share the same connection pool and authentication: + +[source,python] +---- +from thoughtspot_rest_api_sdk import ApiClient, Configuration, UsersApi, MetadataApi + +async with ApiClient(config) as api_client: + users = UsersApi(api_client) + metadata = MetadataApi(api_client) + await users.search_users({"record_offset": 0, "record_size": 10}) +---- + +The following per-tag classes are available: + +[width="100%",cols="1,2"] +[options="header"] +|==== +|Class |Endpoint group +|`AIApi` |AI and Spotter endpoints +|`AuthenticationApi` |Authentication and token management +|`CollectionsApi` |Collections management +|`ConnectionConfigurationsApi` |Connection configuration management +|`ConnectionsApi` |Data connection management +|`CustomActionApi` |Custom actions +|`CustomCalendarsApi` |Custom calendars +|`DBTApi` |dbt integration +|`DataApi` |Data fetch and search +|`EmailCustomizationApi` |Email customization +|`GroupsApi` |User group management +|`JobsApi` |Scheduled job management +|`LogApi` |Audit and security logs +|`ManualTranslationApi` |Manual translation +|`MetadataApi` |Metadata search, TML import/export, tags +|`OrgsApi` |Org management +|`ReportsApi` |Report export (Liveboard, Answer) +|`RolesApi` |Role-based access control +|`SchedulesApi` |Liveboard schedules +|`SecurityApi` |Object sharing and permissions +|`StyleCustomizationApi` |Style and branding customization +|`SystemApi` |System configuration and info +|`TagsApi` |Tag management +|`UsersApi` |User management +|`VariableApi` |Variables +|`VersionControlApi` |Git version control integration +|`WebhooksApi` |Webhook configuration +|`ThoughtSpotRestApi` |Mega-facade — all endpoints +|==== + +=== Accessing response status and headers +Each method has a `*_with_http_info` (and `*_sync_with_http_info`) variant that returns status code, headers, and deserialized data together: + +[source,python] +---- +response = await client.get_current_user_info_with_http_info() +print(response.status_code) +print(response.headers) +print(response.data) +---- + +=== Streaming (SSE) +Endpoints that return SSE streams expose an additional `*_stream` async generator that yields events as they arrive: + +[source,python] +---- +from thoughtspot_rest_api_sdk.models import SendAgentConversationMessageStreamingRequest + +async for event in client.send_agent_conversation_message_streaming_stream( + conversation_identifier="CONVERSATION_ID", + send_agent_conversation_message_streaming_request=( + SendAgentConversationMessageStreamingRequest(messages=["Hello"]) + ), +): + if event.get("type") == "text-chunk": + print(event.get("content", ""), end="", flush=True) +---- + +=== File uploads + +Multipart endpoints accept file content as raw bytes, a `(filename, bytes)` tuple, or an open file handle: + +[source,python] +---- +with open("project.zip", "rb") as f: + await client.dbt_connection( + connection_name="my-connection", + database_name="MY_DB", + import_type="ZIP_FILE", + file_content=f, + ) +---- + +=== File downloads + +Export endpoints return binary content as bytes. Write them to disk using `pathlib.Path`: + +[source,python] +---- +from pathlib import Path + +data = await client.export_liveboard_report( + metadata_identifier="LIVEBOARD_ID", + file_format="PDF", +) +Path("report.pdf").write_bytes(data) +---- + +=== Error handling +API errors raise typed exceptions. Catch by HTTP status code, or catch the base `ApiException`: + +[source,python] +---- +from thoughtspot_rest_api_sdk.exceptions import ( + ApiException, # base class, all API errors + BadRequestException, # 400 + UnauthorizedException, # 401 + ForbiddenException, # 403 + NotFoundException, # 404 + ConflictException, # 409 + UnprocessableEntityException, # 422 + ServiceException, # 5xx +) + +try: + await client.search_metadata({"metadata": [{"type": "LIVEBOARD"}]}) +except UnauthorizedException: + # Refresh credentials and retry + ... +except ApiException as e: + print(e.status, e.reason, e.body, e.headers) +---- + +Every exception exposes `.status`, `.reason`, `.body`, `.data`, and `.headers`. + +=== Retries +Retries are *off by default*. Enable automatic retries with exponential backoff and jitter by setting `retries` on `Configuration`: + +[source,python] +---- +config = Configuration(host=BASE_URL, access_token="...", retries=3) +---- + +When enabled, the SDK retries on `429, 502, 503, 504` status codes and on network or timeout errors. Once the retry budget is exhausted, the final response is returned and raises the usual typed exception. + +[NOTE] +==== +ThoughtSpot uses POST for many read endpoints. POST requests are retried by default. To avoid retrying non-idempotent write calls, restrict the eligible methods: + +[source,python] +---- +config.retry_methods = {"GET", "PUT", "DELETE"} +---- +==== + +=== Configuration reference +[width="100%",cols="2,1,4"] +[options="header"] +|==== +|Option |Default |Description +| `access_token` | `None` | Bearer token string, or a callable returning a token +| `verify_ssl` | `True` | Set `False` for clusters with self-signed certificates +| `ssl_ca_cert` / `ca_cert_data` | `None` | Custom CA bundle (file path / PEM string) +| `cert_file` / `key_file` | `None` | Client certificate and key for mutual TLS +| `proxy` | `None` | Proxy URL, for example, `http://127.0.0.1:8888` +| `connection_pool_maxsize` | `100` | Maximum number of concurrent connections +| `timeout` | `None` | Default request timeout, in seconds (float) or an `httpx.Timeout` +| `connect_timeout` / + +`read_timeout` / + +`write_timeout` / + +`pool_timeout` | `None` | Per-phase default timeouts in seconds; phases left unset default to 300s +| `default_headers` | `{}` | Headers added to every request +| `retries` | `None` (off) | Max retry attempts; set `> 0` to enable automatic retries +| `retry_backoff_factor` | `0.5` | Base seconds for exponential backoff (plus jitter) +| `retry_max_backoff` | `30` | Cap on a single retry's sleep, in seconds +| `retry_statuses` | `{429, 502, 503, 504}` | Status codes that trigger a retry +| `retry_methods` | all | Restrict retries to specific HTTP methods +|==== + +The default request timeout is **300s** when nothing is configured. The timeout and header options are constructor arguments: + +[source,python] +---- +config = Configuration( + host=BASE_URL, + access_token="...", + connect_timeout=5, + read_timeout=60, + default_headers={"X-My-App": "demo"}, +) +---- + +A single call can still override these: +`await client.search_users({...}, _request_timeout=30, _headers={"X-Trace": "1"})`. +`_request_timeout` accepts a float (all phases) or a `(connect, read)` tuple of floats. + +[NOTE] +==== +For clusters with self-signed certificates, disable verification: + +[source,python] +---- +config = Configuration(host=BASE_URL, access_token="YOUR_BEARER_TOKEN", verify_ssl=False) +---- +==== + +=== Updating configuration at runtime + +To apply a new `Configuration` to an existing client, for example, after rotating +credentials or changing timeouts, call `apply_configuration`: + +[source,python] +---- +client.apply_configuration(Configuration(host=BASE_URL, access_token=NEW_TOKEN)) +---- +This rebuilds the underlying API client. For continuous token refresh, you do not +need this. Set `access_token` to a callable; it is invoked +on every request. + +== Documentation for API endpoints + +The full list of available methods is on the `ThoughtSpotRestApi` class. For more information, see link:https://github.com/thoughtspot/rest-api-sdk/blob/release/sdks/python/thoughtspot_rest_api_sdk/api/thought_spot_rest_api.py[thoughtspot_rest_api_sdk/api/thought_spot_rest_api.py, window=_blank]. + +== Additional resources + +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* link:https://pypi.org/project/thoughtspot-rest-api-sdk/[thoughtspot-rest-api-sdk on PyPI, window=_blank] +* link:https://github.com/thoughtspot/rest-api-sdk/tree/release/sdks/python[Python SDK source on GitHub, window=_blank] +* link:https://developers.thoughtspot.com/docs/rest-api-v2[REST API v2.0 Playground, window=_blank] diff --git a/modules/ROOT/pages/rest-api-sdk-libraries.adoc b/modules/ROOT/pages/rest-api-sdk-libraries.adoc index 0db64352d..5b103a7a1 100644 --- a/modules/ROOT/pages/rest-api-sdk-libraries.adoc +++ b/modules/ROOT/pages/rest-api-sdk-libraries.adoc @@ -1,45 +1,67 @@ -= REST API v2.0 SDKs += SDK libraries :toc: true :toclevels: 1 -:page-title: REST API SDKs -:page-pageid: rest-api-sdk -:page-description: Use REST API SDKs to call APIs in a language-specific way. +:page-title: SDK libraries +:page-pageid: rest-api-sdk-libraries +:page-description: ThoughtSpot provides SDK libraries that allow you to integrate ThoughtSpot REST APIs in your application. -ThoughtSpot provides native SDK libraries to help client applications call REST APIs in a specific language format. +ThoughtSpot provides official SDK libraries for integrating REST API v2.0 into your applications. -Currently, the REST API client libraries are available for xref:rest-api-sdk-typescript.adoc[TypeScript] and xref:rest-api-java-sdk.adoc[Java]. These SDKs provide language-specific client libraries to call APIs from client applications. +== Python SDK for REST API v2.0 [.version-badge.new]#New in jul.26.mt# -== Community SDKs -You can use the following open-source, community-supported SDKs. +// SOURCE: SCAL-323283, SCAL-216861 +// SOURCE: PyPI — https://pypi.org/project/thoughtspot-rest-api-sdk/ version 2.26.0b1 +// SOURCE: Python SDK Design Doc — https://docs.google.com/document/d/1AQBCymDS7xGHztMGNzyryjoKkb2em9vW11pTZfyztEA +// ⚠️ GATE — Do not publish until SCAL-216861 is confirmed shipped and stable version is on PyPI. +// TODO: [WRITER] Remove BETA callout and gate comment once stable release is confirmed by Piyush Tayal. +// TODO: [WRITER] Confirm the GitHub repository URL for the Python SDK once available. + +ThoughtSpot provides an official Python SDK for REST API v2.0, enabling Python developers to integrate ThoughtSpot analytics, data operations, and AI workflows directly into Python applications. The SDK is an async-first, fully-typed client generated from the ThoughtSpot OpenAPI specification. [IMPORTANT] ==== -* ThoughtSpot reserves the right to publish its own SDKs to replace or improve upon these community-based SDKs based on customer feedback. -* These community SDKs may not be reviewed or updated periodically for accuracy or completeness, and are not included in ThoughtSpot product support. -* ThoughtSpot-supported SDKs may not be backward-compatible with these community-based SDKs. +// SOURCE: PyPI — version 2.26.0b1 +// TODO: [WRITER] Remove this callout once the stable version is confirmed shipped. +The Python SDK is currently available as a *beta pre-release* (`2.26.0b1`) on PyPI. Confirm the current stable version before using in production. ==== +* *Package name:* `thoughtspot-rest-api-sdk` +* *PyPI:* link:https://pypi.org/project/thoughtspot-rest-api-sdk/[pypi.org/project/thoughtspot-rest-api-sdk, window=_blank] +* *Python:* 3.9 or later +// TODO: [WRITER] Confirm minimum Python version — design doc says 3.9, verify against PyPI metadata. -[width="100%" cols="2,4"] -[options='header'] -|==== -|SDK/ library|Purpose -|link:https://github.com/thoughtspot/thoughtspot_rest_api_python[thoughtspot_rest_api_python, window=_blank] |Python SDK for working with ThoughtSpot's REST APIs + +Install the SDK: -**Language**: Python + +[source,bash] +---- +pip install thoughtspot-rest-api-sdk +---- -|link:https://github.com/thoughtspot/thoughtspot_tml[thoughtspot_tml, window=_blank]| Package for working with ThoughtSpot Modeling Language (TML) files programmatically + +For the full SDK reference, authentication setup, and code examples, see xref:python-sdk.adoc[Python SDK for REST API v2.0]. -**Language**: Python + -|==== +== TypeScript SDK +ThoughtSpot provides an official TypeScript SDK for REST API v2.0, generated from the ThoughtSpot OpenAPI specification. -== Additional resources +// TODO: [WRITER] Confirm the TypeScript SDK section is complete and up to date. +// Add npm package name, install command, and link to TypeScript SDK docs page if available. + +== Java SDK + +ThoughtSpot provides an official Java SDK for REST API v2.0, generated from the ThoughtSpot OpenAPI specification. + +// TODO: [WRITER] Confirm the Java SDK section is complete and up to date. +// Add Maven/Gradle dependency and link to Java SDK docs page if available. -For more information about REST APIs, use the following resources: +== Community SDKs + +The following community-maintained SDK libraries are available for ThoughtSpot REST API integration. These SDKs are not officially supported by ThoughtSpot. + +// TODO: [WRITER] Add confirmed community SDK entries here. + +== Additional resources -* For information about supported authentication types, see xref:authentication.adoc[REST API v2 authentication]. -* Browse through the +++REST API v2 Playground+++ before you start constructing your API requests. The playground offers an interactive portal with comprehensive information about the API endpoints, request and response workflows. -* For information about supported API endpoints, see xref:rest-api-v2-reference.adoc[REST API v2 reference]. -* For information about new and deprecated features and enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2 Changelog]. +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:python-sdk.adoc[Python SDK for REST API v2.0] diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index 452dba9e6..12744fa42 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -203,6 +203,7 @@ Note the version recommendations for your ThoughtSpot instances: [options='header'] |==== |ThoughtSpot release version|Recommended SDK version +a|ThoughtSpot Cloud: 26.8.0.cl | v2.27.0 or later a|ThoughtSpot Cloud: 26.7.0.cl | v2.26.0 or later a|ThoughtSpot Cloud: 26.6.0.cl | v2.25.0 or later a|ThoughtSpot Cloud: 26.5.0.cl | v2.24.0 or later diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index 718d098b8..109bf50fb 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -4,7 +4,7 @@ :page-title: Using REST API v2.0 metadata/search endpoint :page-pageid: rest-apiv2-metadata-search -:page-description: Many use cases are possible with the very V2.0 metadata/search endpoint +:page-description: Many use cases are possible with the V2.0 metadata/search endpoint The `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fsearch-metadata[/metadata/search, target=_blank]` endpoint is the most versatile of all metadata endpoints. It can be used to search for lists or to retrieve very detailed information about specific objects. This endpoint replaces `metadata/list`, `metadata/listobjectheaders`, `metadata/details`, and `metadata/listvizheaders` from REST API v1. @@ -86,7 +86,7 @@ The response from any call to `metadata/search` returns an array of link:https:/ "metadata_detail": null, "metadata_header": {...}, "visualization_headers": null, - "stats": null, + "stats": null }, ... ] @@ -112,7 +112,7 @@ The value of `metadata_header` is a complex object with the most important set o "name": "Snowflake", "description": "Connection to Snowflake data warehouse", "author": "67e15c06-d153-4924-a4cd-ff615393b60f", - "authorName": "UserA, + "authorName": "UserA", "hasLenientDiscoverability": false, "descriptionAutoGenerated": false, "authorDisplayName": "UserA", @@ -3601,7 +3601,7 @@ The `permissions` object takes an array of objects that define a `principal` and The `share_mode` can be `READ_ONLY` ('Can View' in the UI), `MODIFY` ('Can Edit' in the UI), or `NO_ACCESS`, which shows denial of access and is not visible in the UI. === tag_identifiers -Thoughtspot objects can be assigned multiple **tags**, and the `/metadata/search` endpoint allows you to filter for items with a set of tags using the `tag_identifiers` parameter, which takes an array of tag names or GUIDs. +ThoughtSpot objects can be assigned multiple **tags**, and the `/metadata/search` endpoint allows you to filter for items with a set of tags using the `tag_identifiers` parameter, which takes an array of tag names or GUIDs. Including multiple tags behaves as a logical **OR** operation, retrieving all content with **any** of the listed tags. The following request body retrieves any content tagged with `Staging` or `Accounting` tags: @@ -3735,12 +3735,98 @@ The `include_details` parameter in the `metadata/search` API request adds the eq } ---- -The details of each object type is a complex object that is unique to each object type within ThoughtSpot. +The details of each object type are a complex object that is unique to each object type within ThoughtSpot. -The JSON output for `metadata_detail` varies for Liveboards based on the response version specified in the API request. For more information, see xref:rest-api-v2-metadata-search.adoc#lbResponse[Liveboard response format]. +The JSON output for `metadata_detail` varies for Liveboards based on the response version specified in the API request. For more information, see xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[Liveboard response format]. + +=== include_personalised_views +When fetching Liveboard metadata with `include_details: true`, you can also request the list of Personalized Views saved on each Liveboard by setting `include_personalised_views` to `true`. + +This parameter is only applicable to `LIVEBOARD` type objects and has no effect on other metadata types. It requires `include_details` to also be `true` in the same request. + +[source,JSON] +---- +{ + "metadata": [ + { + "type": "LIVEBOARD" + } + ], + "include_details": true, + "include_personalised_views": true +} +---- + +When both parameters are set to `true`, each Liveboard object in the response will include a `personalised_views` array nested within `metadata_detail`: + +[source,JSON] +---- +[ + { + "metadata_id": "4081f38c-1f26-4354-a418-af14136e3bd7", + "metadata_name": "Sales Overview", + "metadata_type": "LIVEBOARD", + "metadata_detail": { + "personalised_views": [ + { + "view_guid": "6e3d11b2-9a4f-4c1e-8b5a-2f3d7e0c1a9d", + "view_name": "Q1 Revenue View", + "author_guid": "59481331-ee53-42be-a548-bd87be6ddd4a", + "author_name": "Alice Johnson", + "is_public": false + }, + { + "view_guid": "a9c42f17-3b8e-4d20-91fa-7c5e2d0b8f3a", + "view_name": "Executive Summary", + "author_guid": "67e15c06-d153-4924-a4cd-ff615393b60f", + "author_name": "Bob Smith", + "is_public": true + } + ] + }, + "metadata_header": {...}, + "visualization_headers": null, + "dependent_objects": null, + "incomplete_objects": null, + "stats": null + } +] +---- + +The `personalised_views` array contains one object per saved Personalized View on the Liveboard. Each object has the following properties: + +[width="100%",cols="2,1,4"] +|==== +|Property|Type|Description + +|`view_guid` +|String +|Unique GUID of the Personalized View. + +|`view_name` +|String +|Display name of the Personalized View as set by its author. + +|`author_guid` +|String +|GUID of the ThoughtSpot user who created this Personalized View. + +|`author_name` +|String +|Display name of the user who created this Personalized View. + +|`is_public` +|Boolean +|If `true`, the Personalized View is shared publicly and visible to other users with access to the Liveboard. If `false`, the view is private to its author. +|==== + +[NOTE] +==== +If a Liveboard has no saved Personalized Views, the `personalised_views` array will be empty (`[]`). If `include_personalised_views` is `false` or omitted, the `personalised_views` key will not appear in `metadata_detail`. +==== === include_dependent_objects -Data objects in ThoughtSpot like Tables and Worksheets have **dependent objects** that connect to them. Liveboards and Answers do not have dependent objects, they can only be a dependent object. +Data objects in ThoughtSpot like Tables and Worksheets have **dependent objects** that connect to them. Liveboards and Answers do not have dependent objects; they can only be a dependent object. An object can only be deleted if all of its dependent objects are deleted first. @@ -3793,7 +3879,7 @@ The `include_hidden_objects`, `include_incomplete_objects`, and `include_auto_cr === Pagination settings -By default, the following pagination settings are applied to the API response retrieved search metadata endpoint: +By default, the following pagination settings are applied to the API response retrieved from the search metadata endpoint: [source,JSON] ---- diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index dfaf6a4ac..2e94f97dc 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -106,9 +106,19 @@ Permanently deletes a saved Spotter agent conversation and all its associated me |ThoughtSpot Cloud: __26.7.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ +a|`POST /api/rest/2.0/ai/memory/import` + +Imports Spotter training memory entries in bulk for backup, migration, or seeding purposes. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/memory/export` + +Exports Spotter training memory entries for audit, backup, or cross-environment migration. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ |===== -- + == Authentication [div boxAuto] @@ -583,6 +593,30 @@ ThoughtSpot Software: __9.0.1.sw or later__ a| |===== -- +== Input tables +[div boxAuto] +-- +[width="100%" cols="8,5,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/input-tables/create` + +Creates a new input table in ThoughtSpot. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/input-tables/{input_table_identifier}/update` + +Writes rows of data into an existing input table. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` + +Deletes an input table. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ +|===== +-- + == Jobs [div boxAuto] diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 0cad327a6..bb291c1f6 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,65 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 26.8.0.cl, August 2026 + +=== Spotter AI APIs + +Spotter training memory APIs::: +ThoughtSpot 26.8.0.cl introduces two new REST API v2.0 endpoints for managing Spotter training memory programmatically: + +* `POST /api/rest/2.0/ai/memory/import` + +Imports Spotter training memory entries in bulk. Use this endpoint to seed training data or migrate Spotter memory across environments. +* `POST /api/rest/2.0/ai/memory/export` + +Exports all current Spotter training memory entries. Use this endpoint to back up training data or audit the current training state. + +For more information, see xref:spotter-ai-memory-api.adoc[Spotter training memory APIs]. + +=== TML import and export + +New TML fields for Personalized Views::: [earlyAccess eaBackground]#Early Access# +Two new fields have been added to the TML for Personalized Views. You can see these fields added to the TML schema when you export through the `POST /api/rest/2.0/metadata/tml/export` API. + +* A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. +* Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. + +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 APIs. 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. ++ + +=== Input tables API +ThoughtSpot introduces three new REST API v2.0 endpoints for managing input tables programmatically. Input tables allow structured data to be written directly into ThoughtSpot for use in Worksheets and Liveboards. + +* `POST /api/rest/2.0/input-tables/create` + +Creates a new input table. Accepts the table name, column schema, and connection configuration in the request body. + +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` + +Updates (upserts) rows in the specified input table. The `input_table_identifier` is the GUID of the target input table. + +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` + +Deletes rows from the specified input table matching the supplied filter criteria. + +=== Roles API + +Granular download privileges::: +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. + +These privileges are configurable via the `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` API endpoints. + +=== Liveboard schedules API +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. + +=== REST API Python SDK +The REST API Python SDK library artifacts are now available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. For information about the python SDK library, see xref:rest-api-python-sdk.adoc[Python SDK]. + == Version 26.7.0.cl, July 2026 === Spotter AI APIs @@ -53,8 +112,8 @@ The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving t Enhancements:: -* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. -* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activate status, resetting authentication, signature verification, and storage destination properties. +* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring a GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. +* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activation status, resetting authentication, signature verification, and storage destination properties. * API requests to the `/api/rest/2.0/system/communication-channels/validate` now return GCS storage properties in response. === Communication channel monitoring @@ -80,7 +139,6 @@ Uploads a custom font file to ThoughtSpot. * `POST /api/rest/2.0/customization/styles/fonts/search` + Returns custom fonts uploaded to the instance. -//Use the `include_font_assignments` parameter to include information about which visualization elements each font is assigned to. * `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + Updates the display name, weight, style, or color of an existing custom font. @@ -165,7 +223,7 @@ 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. +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^ @@ -178,7 +236,7 @@ For more information, see xref:collections.adoc#share-collection[Share a Collect == 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. +You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to the `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. === Spotter APIs @@ -239,6 +297,20 @@ The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF download For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. +=== Metadata search API enhancements + +Personalized Views in metadata search:: +The `POST /api/rest/2.0/metadata/search` API endpoint introduces the `include_personalised_views` request parameter. + +When both `include_details: true` and `include_personalised_views: true` are specified in the request, the API returns a `personalised_views` array in the `metadata_detail` object for `LIVEBOARD` metadata type responses. + +This allows you to retrieve the full list of Personalized Views associated with a Liveboard in a single API call, without requiring a separate TML export. + +For more information, see xref:rest-api-v2-metadata-search.adoc#_include_personalised_views[Search metadata API]. + +=== TML API enhancements +You can now import Liveboards with more than 100 associated Personalized views. For more information, see the xref:tml-api.adoc[TML API documentation]. + == Version 26.4.0.cl, April 2026 === Variable API endpoints @@ -439,7 +511,7 @@ Sets a communication channel preference for all Orgs at the cluster level or at * `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]. +For more information, see xref:webhooks-comm-channel.adoc[Configure and monitor communication channels]. Webhook:: The following APIs are introduced for webhook CRUD operations: @@ -475,8 +547,6 @@ The variable API enhancements are listed in the following sections. For addition * 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# @@ -522,9 +592,6 @@ Breaks down a user-submitted query into a series of analytical sub-questions usi * `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:: @@ -706,10 +773,6 @@ For information about how to install and use the SDK, see xref:rest-api-java-sdk === 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. + @@ -763,12 +826,6 @@ The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow * `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: @@ -815,11 +872,6 @@ Indicates if the TMLs with large and complex metadata should be validated before + 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. @@ -893,14 +945,6 @@ User session:: ** `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: @@ -1077,7 +1121,7 @@ For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[ 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 9.7.0.cl, November 2023 === Version Control APIs @@ -1306,7 +1350,7 @@ 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]: +The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[runtime filters] and xref:runtime-sort.adoc[sorting column data]: + ** `POST /api/rest/2.0/report/liveboard` + ** `POST /api/rest/2.0/report/answer` diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 01b02b423..ed69d22ad 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -6,9 +6,8 @@ :page-pageid: security-settings :page-description: Security settings for embedding - ThoughtSpot allows administrators and developers to configure allowlists for Content Security Policy (CSP) and Cross-origin Resource Sharing (CORS), authentication attributes, and access control settings. -These settings can be done via the **Security Settings** page in the ThoughtSpot UI, or through REST APIs v2, by sending a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. +These settings can be done via the **Security Settings** page in the ThoughtSpot UI, or through REST APIs v2, by sending a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. == Overview Most web browsers block cross-site scripting, cross-domain requests, and third-party cookies by default. Web browsers also have built-in security mechanisms such as same-origin and content security policies. These policies restrict how applications and scripts from one origin (domain) can interact with the resources hosted on another origin (domain). To ensure data security and a seamless user experience in embedding applications, configure the settings described in this section. @@ -20,11 +19,11 @@ To avoid this issue, ThoughtSpot recommends the following: * Developers can use either xref:embed-authentication.adoc#embedSSO[`AuthType.EmbeddedSSO`] or xref:trusted-auth-sdk.adoc[`AuthType.TrustedAuthTokenCookieless`] based on their embedding setup. * If you are using a ThoughtSpot Cloud instance, set up your instance to the same domain as your host application. For more information, see link:https://docs.thoughtspot.com/cloud/latest/custom-domains[Custom domain configuration, window=_blank]. -* If you are using authentication methods that rely on cookies, xref:_enable_partition_cookies[enable partition cookies]. +* If you are using authentication methods that rely on cookies, xref:_enable_partitioned_cookies[enable partitioned cookies]. == Configure security settings -Users with administration privileges can configure security settings on the Security settings page of the ThoughtSpot UI, or by sending a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Note that the following settings on the **Security Settings** page will appear as locked for ThoughtSpot Analytics application users and will require an embedding license: +Users with administration privileges can configure security settings on the Security settings page of the ThoughtSpot UI, or by sending a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Note that the following settings on the **Security Settings** page will appear as locked for ThoughtSpot Analytics application users and will require an embedding license: * xref:security-settings.adoc#csp-viz-embed-hosts[CSP visual embed hosts] * xref:security-settings.adoc#cors-hosts[CORS whitelisted domains] @@ -37,7 +36,7 @@ Users with administration privileges can configure security settings on the Secu On ThoughtSpot instances with Orgs, security settings can be managed at two levels: * Global settings for all Orgs (cluster level) + -Cluster administrators can configure security settings globally for all Orgs. On ThoughtSpot instances with Orgs, the *Develop* page opens in the `Primary Org` context, unless you are accessing the Develop tab from a specific Org context. To configure settings for all Orgs, you must switch to *All Orgs* context. +Cluster administrators can configure security settings globally for all Orgs. On ThoughtSpot instances with Orgs, the *Develop* page opens in the *Primary Org* context, unless you are accessing the Develop tab from a specific Org context. To configure settings for all Orgs, you must switch to the *All Orgs* context. * Org-level settings + Cluster and Org administrators can configure security settings for the current logged-in Org. Configuration modifications at the Org level do not affect other Orgs or the default settings applied at the All Orgs level. @@ -69,7 +68,7 @@ The following table shows the settings available at the All Orgs and per-Org lev |SAML SSO |**SAML redirect domains** a|[tag greenBackground tick]#Yes# a| [tag redBackground tick]#No# |Token-based authentication|**Trusted authentication** a|[tag greenBackground tick]#Yes# + -Can be used to authenticate users in any Org on the ThoughSpot instance. a| +Can be used to authenticate users in any Org on the ThoughtSpot instance. a| [tag greenBackground tick]#Yes# + Each Org can have a separate secret key, which can be used to authenticate users in that Org. |===== @@ -91,7 +90,7 @@ Each Org can have a separate secret key, which can be used to authenticate users To allow another application to embed ThoughtSpot, you must xref:security-settings.adoc#csp-viz-embed-hosts[add your host application domain as a CSP Visual Embed host]. -To allow xref:security-settings.adoc#csp-connect-src[loading script interfaces and JavaScript events for custom actions], or xref:security-settings.adoc#csp-trusted-domain[to enable importing resources from other sites], add the source domain URLs as trusted hosts in the respective CSP allowlist. +To allow xref:security-settings.adoc#csp-connect-src[loading script interfaces and JavaScript events for custom actions] or xref:security-settings.adoc#csp-trusted-domain[importing resources from other sites], add the source domain URLs as trusted hosts in the respective CSP allowlist. [NOTE] ==== @@ -102,23 +101,23 @@ If your instance has Orgs configured, note that the default Org on your instance ==== Add CSP visual embed hosts To allow your host domain to set the `frame-ancestors` CSP policy header and embed a ThoughtSpot object within your application frame, add your application domain as a CSP visual embed host. -. On your ThoughtSpot application instance, go to *Develop* page. -. 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 the domain names. For valid domain name formats, See xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration]. -. Click *Save changes*. - - [NOTE] ==== Only users with a valid embed license can add Visual Embed hosts. ==== -*Through the REST API v2* +In the UI:: -Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add your application domain as a CSP visual embed host for your ThoughtSpot application instance by entering valid values for the parameter `visual_embed_hosts`. +. On your ThoughtSpot application instance, go to the *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 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 request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add your application domain as a CSP visual embed host for your ThoughtSpot application instance by entering valid values for the parameter `visual_embed_hosts`. ++ [source,cURL] ---- curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \ @@ -141,18 +140,19 @@ curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/c ==== Add URLs to CSP connect-src allowlist If you plan to use a custom action or webhook to send data to an external endpoint or application, you must add the domains of the target endpoints or applications to the `CSP connect-src` allowlist. -. On your ThoughtSpot application instance, go to *Develop* page. +In the UI:: +. On your ThoughtSpot application instance, go to the *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]. +. 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. +Through the REST API v2:: +Send a request to the `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 \ @@ -173,11 +173,11 @@ curl -X POST \ [#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. +In the UI:: +. On your ThoughtSpot application instance, go to the *Develop* page. . If your instance has Orgs, click the *All Orgs* tab. . Go to *Customizations* > *Security settings* and configure the settings: + @@ -195,14 +195,16 @@ Add the domains from which you want host scripts. For more information, see xref Add the iframe source URL domains. //// +Through the REST API v2:: +Send a request to the `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. -*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 \ @@ -232,11 +234,11 @@ curl -X POST \ }' ---- - ==== 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: +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. +In the UI:: +. On your ThoughtSpot application instance, go to the *Develop* page. . If your instance has Orgs, click the *All Orgs* tab. . Go to *Customizations* > *Security settings*. . Click *Edit*. @@ -244,10 +246,10 @@ Features such as link:https://docs.thoughtspot.com/software/latest/liveboard-not . Click *Save changes*. -*Through the REST API v2* - -Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add domain URLs of external sites using iFrame content are added to the `iframe_src_urls` parameter for your ThoughtSpot application instance. +Through the REST API v2:: +Send a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add domain URLs of external sites using iFrame content to the `iframe_src_urls` parameter for your ThoughtSpot application instance. ++ [source,cURL] ---- curl -X POST \ @@ -267,31 +269,32 @@ curl -X POST \ [#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: +In the UI:: +To add domain names to the CORS allowlist, complete 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. + +. 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. +* To configure CORS settings at the Org level, switch the Org context via the Org switcher in the top navigation bar. -. On *Develop* page, go to *Customizations* > *Security settings*. +. On the *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]. +. 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* +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 request to the `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 \ @@ -315,6 +318,77 @@ curl -X POST \ ---- +[#custom-app-schemes] +==== Allow custom app schemes for mobile and hybrid embeds +If you are embedding ThoughtSpot in a mobile or hybrid application built with frameworks such as Capacitor or Ionic, your application may use a custom URL scheme (for example, `capacitor://localhost` or `ionic://localhost`) rather than an `https://` origin. + +To allow these origins to embed ThoughtSpot content, add the custom scheme URL to the *CSP visual embed hosts* and *CORS whitelisted domains* allowlists. + +[IMPORTANT] +==== +Before allowlisting custom schemes, note that allowlisting a shared app scheme such as `capacitor://localhost` or `ionic://localhost` does not uniquely identify your application. Any application on the same device that uses the same framework presents the same origin to the browser. This means: + +* Allowlisting `capacitor://localhost` grants embedding access to *all* Capacitor-based apps on that device, not just yours. +* Treat custom-scheme allowlisting as *enabling functionality*, not as an access control boundary. +* Security for these embeds must be enforced through *authentication* — use xref:trusted-auth-sdk.adoc[`AuthType.TrustedAuthTokenCookieless`] (cookieless trusted auth) to ensure that only authenticated users in your application can access ThoughtSpot content. +* Do *not* rely on origin allowlisting alone as a security mechanism for custom-scheme embeds. +==== + +===== Add a custom scheme to CSP visual embed hosts + +. On your ThoughtSpot application instance, go to *Develop* > *Customizations* > *Security settings*. +. Click *Edit*. +. In the *CSP visual embed hosts* text box, add your custom scheme URL. For example: ++ +---- +capacitor://localhost +---- +. Click *Save changes*. + +===== Add a custom scheme to CORS whitelisted domains +. On your ThoughtSpot application instance, go to *Develop* > *Customizations* > *Security settings*. +. Click *Edit*. +. In the *CORS whitelisted domains* text box, add your custom scheme URL. For example: + +`capacitor://localhost` +. Click *Save changes*. + +===== Add a custom scheme via REST API +Send a request to the `POST /api/rest/2.0/system/security-settings/configure` endpoint and add the custom scheme URL to the `visual_embed_hosts` and `cors_whitelisted_urls` arrays: + +[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' \ + --data-raw '{ + "org_preferences": [ + { + "visual_embed_hosts": [ + "capacitor://localhost" + ], + "cors_whitelisted_urls": [ + "capacitor://localhost" + ] + } + ] +}' +---- + +After allowlisting the custom scheme, initialize the Visual Embed SDK using `AuthType.TrustedAuthTokenCookieless` in your Capacitor or Ionic application: + +[source,JavaScript] +---- +import { init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://your-thoughtspot-instance.thoughtspot.cloud', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/get-token') + .then(r => r.json()) + .then(d => d.token), + }); +---- + [#csp-cors-hosts] ==== Domain name format for CSP and CORS configuration @@ -324,8 +398,8 @@ curl -X POST \ * 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. +** 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**: + @@ -424,10 +498,12 @@ If you have embedded ThoughtSpot content in your app, you may want your users to *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. +Send a request to the `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] ---- @@ -460,7 +536,7 @@ Many web browsers do not allow third-party cookies. If you are using authenticat 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. +. On your ThoughtSpot application instance, go to the *Develop* page. . If your instance has Orgs, click the *All Orgs* tab. . Go to *Customizations* > *Security settings*. . Click *Edit*. @@ -476,7 +552,7 @@ Safari blocks all third-party cookies and does not support partitioned cookies. *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 . +Send a request to the `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] ---- @@ -498,12 +574,12 @@ To find the trusted authentication configuration for the specified auth type at 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. +See xref:trusted-authentication.adoc[Trusted authentication] and xref:trusted-auth-secret-key.adoc[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 retrieve the security settings for your ThoughtSpot instance by sending a request to the `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] diff --git a/modules/ROOT/pages/spotter-ai-memory-api.adoc b/modules/ROOT/pages/spotter-ai-memory-api.adoc new file mode 100644 index 000000000..faad2aa20 --- /dev/null +++ b/modules/ROOT/pages/spotter-ai-memory-api.adoc @@ -0,0 +1,685 @@ += Spotter training memory migration API +:toc: true +:toclevels: 2 + +:page-title: Spotter training memory migration API +:page-pageid: spotter-memory-migration +:page-description: Use the AI memory REST API v2 endpoints to export and import Spotter training memory across ThoughtSpot environments. +:keywords: Spotter memory, AI memory, memory migration, memory export, memory import, Spotter training, REST API + +[beta betaBackground]#Beta# + +ThoughtSpot provides public REST API v2 endpoints to import and export memory for the following purposes: + +* To promote validated Spotter knowledge from a development environment to production. +* To replicate a gold-standard Spotter configuration across multiple Orgs at scale. +* To back up and restore Spotter memory as part of your deployment pipeline. + +[NOTE] +==== +The API endpoints support importing and exporting memory with rules defined at the model level and recipes. Exporting or importing user memory and analyst memory are currently not supported. +==== + +== Memory migration workflow +Spotter accumulates training memory, which includes *rules* (business logic) and *recipes* (query patterns), as users interact with data models. To migrate Spotter memory from one data model to another, or from a source environment to a target environment: + +. <> + +Call `POST /api/rest/2.0/ai/memory/export` with the GUIDs of the data models to migrate. +. <> + +Save and modify the exported file as needed. +. <> + +Call `POST /api/rest/2.0/ai/memory/import` to import Spotter memory content into ThoughtSpot. You can validate the import operation using the dry run operation and review `import_summaries` and `failures` before proceeding. + +=== Required permissions +To use Spotter memory migration APIs, the user requires the following privileges: + +* *Can manage Spotter* and at least view access to the data model. +* *Can use Spotter* and edit access to the data model, or `SPOTTER_COACHING_PRIVILEGE` to import memory entries. + +Users with administration access can also export and import Spotter memory. + +[#export-memory] +== Exporting Spotter memory +The `/api/rest/2.0/ai/memory/export` API endpoint allows you to export the Spotter memory records, including rules and recipes for the specified data models as a single YAML payload. The payload can be edited locally and re-submitted through the import memory API. The exported file can be reviewed, edited, and imported into a ThoughtSpot Org or another environment. + +=== Request parameters +[cols="2,4", options="header"] +|=== +|Parameter | Description +| `sources` +a|__Array of strings__. A list of data models from which you want to export. +Specify the following attributes: + +* `type`. __String__. The source object type. Default value is `DATA_MODEL`. This is the default source type for Spotter memory, which includes the rules, recipes, and always-apply rules attached directly to a data model. +* `identifiers`. __Array of strings__. GUIDs or object IDs of the data models. +|| +|=== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/memory/export' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "sources": [ + { + "type": "DATA_MODEL", + "identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + } + ] +}' +---- + +=== Example response +The API returns a response object with the following details: + +* `content` + +The serialized memory payload in YAML format. The exported file includes an array of memories, including rules and recipes added to Spotter memory, and data model GUID and object ID if present. +* `type` + +Indicates if the memory type is `RULE` or `RECIPE`. If the type is `RULE`, the response shows the rule definition. If the type is `RECIPE`, the contents of the recipe such as task, steps, TML tokens are included in the response. +* `datamodel_sources` + +GUID and object ID of the data model object. + +You can edit it locally and import it into your environment using the import memory API endpoint. + +[source,JSON] +---- +{ + "content":{ + "memories":[ + { + "type":"RULE", + "content":{ + "rule_definition":"Revenue is defined as Sales Monthly." + }, + "datamodel_sources":[ + { + "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca", + "obj_id":"SampleRetail-Apparel-cd252e5c" + } + ], + "tags":[ + + ] + }, + { + "type":"RULE", + "content":{ + "rule_definition":"Hot products: top 20 products by sales." + }, + "datamodel_sources":[ + { + "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca", + "obj_id":"SampleRetail-Apparel-cd252e5c" + } + ], + "tags":[ + "GLOBAL" + ] + }, + { + "type":"RULE", + "content":{ + "rule_definition":"Sales operations are organized into three geographic regions: east, midwest, and west." + }, + "datamodel_sources":[ + { + "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca", + "obj_id":"SampleRetail-Apparel-cd252e5c" + } + ], + "tags":[ + "GLOBAL" + ] + }, + { + "type":"RECIPE", + "content":{ + "user_query":"Weekly sales for June", + "recipe":{ + "task":"Show total sales by week for the month of June", + "steps":[ + { + "instruction":"Query sales by weekly date filtered to June month", + "analytical_mappings":{ + "tml_tokens":[ + "[sales]", + "[date].weekly", + "[date] = 'june'" + ], + "formulas":[ + + ] + } + } + ] + } + }, + "datamodel_sources":[ + { + "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca", + "obj_id":"SampleRetail-Apparel-cd252e5c" + } + ], + "tags":[ + + ] + }, + { + "type":"RECIPE", + "content":{ + "user_query":"What is the total sales by date?", + "recipe":{ + "brief_summary":"Visualizes total sales revenue over time on a daily basis.", + "nl_query":"What is the total sales by date?", + "lossy_tml_tokens":"[date] [sales]", + "lossy_formulas":[ + + ] + } + }, + "datamodel_sources":[ + { + "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca", + "obj_id":"SampleRetail-Apparel-cd252e5c" + } + ], + "tags":[ + + ] + }, + { + "type":"ALWAYS_APPLY_RULES", + "content":{ + "rules":[ + "When asking for 'top' results without specifying a number, default to top 20", + "Use sales column as primary metric; if sales data unavailable, fall back to quantity purchased column" + ] + }, + "datamodel_sources":[ + { + "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca", + "obj_id":"SampleRetail-Apparel-cd252e5c" + } + ], + "tags":[ + + ] + } + ] + } +} +---- + +[#update-memory-file] +== Updating the memory file content +The export memory API endpoint returns a YAML payload with a single top-level `memories` key holding a list of memory items. It includes the following object properties: + +* `type` + +A typed `content` block, indicating `RULE` or `RECIPE`. +* `datamodel_sources` list + +GUID and object ID of the data models. +* `tags` __Optional__. + +You can modify this file, add target data models, and submit it back through the import memory API endpoint. + +[source,yaml] +---- +memories: +- type: RULE + content: + rule_definition: "Revenue is defined as Sales Monthly." + datamodel_sources: + - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506 + obj_id: RetailSales-3bc18302 + tags: [] + +- type: RULE + content: + rule_definition: "Hot products: top 20 products by sales." + datamodel_sources: + - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506 + obj_id: RetailSales-3bc18302 + tags: + - GLOBAL + +- type: RULE + content: + rule_definition: "Sales operations are organized into three geographic regions: east, midwest, and west." + datamodel_sources: + - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506 + obj_id: RetailSales-3bc18302 + tags: + - GLOBAL + +- type: RECIPE + content: + user_query: "Weekly sales for June" + recipe: + task: "Show total sales by week for the month of June" + steps: + - instruction: "Query sales by weekly date filtered to June month" + analytical_mappings: + tml_tokens: + - "[sales]" + - "[date].weekly" + - "[date] = 'june'" + formulas: [] + datamodel_sources: + - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506 + obj_id: RetailSales-3bc18302 + tags: [] + +- type: RECIPE + content: + user_query: "What is the total sales by date?" + recipe: + brief_summary: "Visualizes total sales revenue over time on a daily basis." + nl_query: "What is the total sales by date?" + lossy_tml_tokens: "[date] [sales]" + lossy_formulas: [] + datamodel_sources: + - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506 + obj_id: RetailSales-3bc18302 + tags: [] + +- type: ALWAYS_APPLY_RULES + content: + rules: + - "When asking for 'top' results without specifying a number, default to top 20" + - "Use sales column as primary metric; if sales data unavailable, fall back to quantity purchased column" + datamodel_sources: + - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506 + obj_id: RetailSales-3bc18302 + tags: [] +---- + +A file can contain multiple `RULE` and multiple `RECIPE` items for a data model, but at most one `ALWAYS_APPLY_RULES` item per data model. + +=== Memory item fields +[cols="2,4", options="header"] +|=== +| Field | Description +| `type` | Type can be `RULE`, `RECIPE`, or `ALWAYS_APPLY_RULES`. + + +* `RULE`. A single semantic rule. The content for this type must include `rule_definition` and the data model IDs. +* `RECIPE`. A serialized string that includes responses to the natural-language query. +* `ALWAYS_APPLY_RULES`. Mandatory rules that must always apply when generating queries for the data model. The content must include a `rules` list. +| `content` | Type-specific content block. +| `datamodel_sources` a| The data models the memory attaches to. Each item must list at least one source. Each entry identifies a data model via: + +* `guid`: the data model GUID. +* `obj_id`: A stable object ID, resolved to a GUID server-side. + +If both are supplied, `obj_id` takes precedence and `guid` is ignored entirely; `guid` takes effect only when `obj_id` is absent. Exported files populate `guid` and, if present, `obj_id` as well. + +[IMPORTANT] +==== +When `obj_id` is present, the accompanying `guid` is not used as a fallback. If an `obj_id` does not exist in the target environment, that item fails with `UNRESOLVED_SOURCE`. Remove or replace the stale `obj_id` values before importing across environments. +==== + +| `tags` |Free-form labels. +|| +|=== + +[#memory-file-limits] +=== Limits +Note the following limits for the import file and its content: + +[cols="2,1", options="header"] +|=== +| Limit | Default +| Uploaded file size | 10 MiB +| Total memory items | 10,000 +| `rule_definition` length | 1,000 characters +| `user_query` length | 1,000 characters +| `recipe` length | 2,000 characters +| `rules` combined length (`ALWAYS_APPLY_RULES`) | 2,000 characters + +The `rules` limit in `ALWAYS_APPLY_RULES` applies to the combined length across all entries in the list, not per entry. +| Tags per item | 10 +| Characters per tag | 50 +|| +|=== + +[#structure-rules] +=== Structural rules +* The document must be a mapping with a `memories` key whose value is a list. +* Unknown keys at the top level, within an item, or under `content` are rejected. +* Each item's `type` must be one of the three supported values, and `content` must match that type's shape. +* Null, empty-string, or incorrect type values in a required field are treated as missing. +* Non-string or empty `tags` entries are dropped; certain tags reserved for internal use are stripped automatically before the item is stored. + +[#cross-item-rules] +=== Cross-item rules +A data model referenced by more than one `ALWAYS_APPLY_RULES` item is rejected. Combine them into a single item's `rules` list. + +[#import-memory] +== Importing Spotter memory +The `/api/rest/2.0/ai/memory/import` API endpoint imports Spotter memory content from a YAML payload into a target data model in your ThoughtSpot environment. Use this API endpoint to migrate Spotter memory with rules and recipes when seeding a new data model, or moving content across Orgs or between different environments. + +[IMPORTANT] +==== +* The import operation *replaces* the existing memory of the target data models with the YAML content. The import operation uses a targeted replacement model, not an append. To incrementally sync changes, export the relevant memory filtered by time window using the export memory API endpoint, merge with your existing file manually, and upload the merged result. +* The import replaces memory entries only for the data models referenced in the uploaded file. +* Since import replaces the existing memory entries, ThoughtSpot strongly recommends using the `dry_run` mode to validate before committing the content to the data model. +* The API operation does not include semantic or column-level validation, so you must ensure that the column names are valid in the target environment. +* If any part of the import fails, all changes are rolled back. +==== + +=== Request parameters + +Pass the following parameters in the API request body. + +[cols="2,4", options="header"] +|=== +| Parameter | Description +| `content` +|__String__. The full contents of the Spotter memory payload YAML file passed as a string. The content structure is the same as the payload received from the export memory API endpoint. The memory payload will be imported to the data models specified in the `datamodel_sources` property of the content string. For more information about the contents and structure of the import file, see xref:spotter-ai-memory-api.adoc#update-memory-file[Updating the memory file content]. + +| `dry_run` +a|__Boolean__. Controls whether the import runs as a preview or executes for real. + + +* When set to `true`, the API validates the memory payload and returns preview counts without writing anything to the target data models. ThoughtSpot recommends running a dry run first to inspect validation errors before committing. + +* When set to `false`, the API executes the import. The import replaces the existing global memories on the data models referenced in the payload with the entries supplied in the payload. If the import fails, ThoughtSpot rolls back the target to its pre-import state. + +|| +|=== + +=== Dry run operation +The import operation deletes and replaces the existing global memories on the referenced data models. ThoughtSpot strongly recommends using a `dry_run` to validate the payload and preview the results. + +* If the API returns validation errors, verify the `validation_failures` and `diagnostics` fields in the API response and fix errors if any. +* If the API returns a clean preview without any validation errors, call the API again with `dry_run` set as `false`. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/memory/export' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "content": "{ \"content\": \"memories:\\n- type: RULE\\n content:\\n rule_definition: Revenue is defined as Sales Monthly.\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: RULE\\n content:\\n rule_definition: \\\"Hot products: top 20 products by sales.\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: RULE\\n content:\\n rule_definition: \\\"Sales operations are organized into three geographic regions: east, midwest, and west.\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags:\\n - GLOBAL\\n- type: RECIPE\\n content:\\n user_query: Weekly sales for June\\n recipe: \\\"{\\\\\\\"task\\\\\\\": \\\\\\\"Show total sales by week for the month of June\\\\\\\", \\\\\\\"steps\\\\\\\": [{\\\\\\\"instruction\\\\\\\": \\\\\\\"Query sales by weekly date filtered to June month\\\\\\\", \\\\\\\"analytical_mappings\\\\\\\": {\\\\\\\"tml_tokens\\\\\\\": [\\\\\\\"[sales]\\\\\\\", \\\\\\\"[date].weekly\\\\\\\", \\\\\\\"[date] = '\''june'\''\\\\\\\"], \\\\\\\"formulas\\\\\\\": []}}]}\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: RECIPE\\n content:\\n user_query: Compare this quarter'\''s sales with previous quarter by region\\n recipe: \\\"{\\\\\\\"task\\\\\\\": \\\\\\\"Compare total sales by region for this quarter versus previous quarter\\\\\\\", \\\\\\\"steps\\\\\\\": [{\\\\\\\"instruction\\\\\\\": \\\\\\\"Query total sales by region for this quarter compared to previous quarter\\\\\\\", \\\\\\\"analytical_mappings\\\\\\\": {\\\\\\\"tml_tokens\\\\\\\": [\\\\\\\"sales\\\\\\\", \\\\\\\"date = '\''this quarter'\''\\\\\\\", \\\\\\\"date = '\''last quarter'\''\\\\\\\", \\\\\\\"region\\\\\\\"], \\\\\\\"formulas\\\\\\\": []}}]}\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: RECIPE\\n content:\\n user_query: What is the total sales by date?\\n recipe: |-\\n 1. Brief Answer Summary\\n {\\n \\\"brief_summary\\\": \\\"Visualizes total sales revenue over time on a daily basis.\\\",\\n \\\"nl_query\\\": \\\"What is the total sales by date?\\\",\\n \\\"display_tml_tokens\\\": \\\"\\\"\\n }\\n\\n 2. Call NLSV2_Tool with these arguments\\n {\\n \\\"lossy_tml_tokens\\\": \\\"[date] [sales]\\\",\\n \\\"lossy_formulas\\\": []\\n }\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: ALWAYS_APPLY_RULES\\n content:\\n rules:\\n - \\\"When asking for '\''top'\'' results without specifying a number, default to top 20\\\"\\n - \\\"Use sales column as primary metric; if sales data unavailable, fall back to quantity purchased column\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n\" }", + "dry_run": true +}' +---- + +=== Example response + +[source,JSON] +---- +{ + "status": "SUCCESS", + "summary": [ + { + "memory_type": "RULES", + "source": { + "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506", + "type": "DATA_MODEL" + }, + "existing_record_count": 3, + "deleted_record_count": 3, + "inserted_record_count": 3, + "failed_record_count": 0 + }, + { + "memory_type": "RECIPES", + "source": { + "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506", + "type": "DATA_MODEL" + }, + "existing_record_count": 3, + "deleted_record_count": 3, + "inserted_record_count": 3, + "failed_record_count": 0 + }, + { + "memory_type": "ALWAYS_APPLY_RULES", + "source": { + "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506", + "type": "DATA_MODEL" + }, + "existing_record_count": 0, + "deleted_record_count": 0, + "inserted_record_count": 1, + "failed_record_count": 0 + } + ], + "validation_failures": [], + "diagnostics": [], + "operation_id": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506" + } +---- + + +=== Response parameters +Based on the status of the import operation, the API returns a response code. Note that the `200` response does not guarantee a successful import. Verify the `status` field in the response body to ensure there are no validation errors. + +[cols="2,5", options="header"] +|=== +| Parameter | Description +| `status` +| Terminal status of the import operation. After an import operation, the 200 response can include one of the following status values: + +* `SUCCESS` to indicate a successful import. +* `VALIDATION_FAILED`. File or row-level validation failed before any data was written. Inspect `validation_failures` for per-item error details. +* `FAILED` to indicate that the import operation has failed. Verify the diagnostics section. + +A `sub_status` of `ROLLED_BACK` means all changes are rolled back and the original memory is intact. + +A `sub_status` of `FAILURE` indicates a non-rollback error. +| `summary` +a| Per data model and memory type result entries. Null when the import failed before any record processing occurred. Each entry in the `summary` array covers one (memory type, target data model) combination. + +* `memory_type`: Type of memory these counts apply to: `RULES`, `RECIPES`, or `ALWAYS_APPLY_RULES`. +* `source`: Data source type and ID. Type is always `DATA_MODEL`. +* `existing_record_count`: Number of memory entries of this type that existed on the target data model before the import. +* `deleted_record_count`: Number of existing entries that were deleted during the import operation. +* `inserted_record_count`: Number of entries from the memory file that were inserted. +* `failed_record_count`: Number of records of this type that failed validation or processing. + +| `validation_failures` +a| Per-item validation failure entries. + +* `line_number`: Best-effort line number of the offending item in the YAML file. May be null when the line cannot be determined. +* `reason`: Machine-readable category for the failure. For more information, see xref:spotter-ai-memory-api.adoc#validation-error-reference[Validation errors]. +* `field_name`: Dotted path to the offending field within the item. For example, `content.rule_definition`. Absent when the failure is at the item level rather than the field level. +* `message`: Human-readable description of the failure. + +| `diagnostics` +a| Diagnostic message groups for fatal errors, rollbacks, and non-fatal warnings, each grouped by severity. + +`sub_status`:: +Severity or disposition of this diagnostic group: + +** `WARNING`: The import succeeded but with non-fatal caveats. For example, some older memory entries could not be fully cleaned up. +** `FAILURE`: A fatal error prevented the import from completing. The state of memory on the target may be unpredictable. +** `ROLLED_BACK`: The insert of new memory entries failed. Every successful insert was undone and the original memory is intact. +** `UNKNOWN`: Uncategorized diagnostic. + +`messages`:: +Human-readable messages for this diagnostic group. + +| `operation_id` +a| Server-generated identifier for this import operation. Include this value in support tickets to correlate server-side logs with the request. +|| +|=== + +=== Validations reference +The payload is fully validated before anything is written irrespective of the `dry_run` parameter setting. If any item fails validation, the entire import is rejected, with the failure details returned in the response. + +To avoid validation errors: + +* Ensure that the memory file and its content do not exceed the xref:spotter-ai-memory-api.adoc#memory-file-limits[limits]. A data model referenced by more than one `ALWAYS_APPLY_RULES` item is rejected. Ensure that you combine them into a single item's `rules` list. +* The content string does not include any unknown keys at the top level, within an item, or under `content`. +* Ensure that the `type` for each item is set to the three supported values (`RULE`, `RECIPE`, and `ALWAYS_APPLY_RULES`), and the `content` string for each memory entry matches that type's shape and all required fields are defined. +* Ensure that there are no non-string or empty `tags`. Certain tags reserved for internal use are stripped automatically before the item is stored. + +[#validation-error-reference] +=== Validation error reference + +If the validation fails, the API returns `200` with a terminal `status` of `VALIDATION_FAILED` or `FAILED`, and includes the details in the `validation_failures` and `diagnostics` sections of the API response. + +* *VALIDATION_FAILED*: Indicates schema or semantic validation failure. Inspect `validation_failures` and fix the items. Each entry in `validation_failures` carries one of the following error types: + +** `SCHEMA`: Indicates that YAML structure is invalid or malformed. +** `VALIDATION`: Indicates that a required field is missing, exceeds the limit, or an incorrect GUID. +** `CHAR_LIMIT`: Indicates that a content field exceeds the character limit. +** `UNRESOLVED_SOURCE`: A referenced data model GUID could not be resolved on the target. Check that all GUIDs in the memory file correspond to data models that exist on the target environment. +** `ACCESS_DENIED`: The user making the API request does not have edit access on a referenced data model. +* *FAILED*: Indicates incomplete import. Inspect `diagnostics` to verify the errors. + +==== Validation failure response + +Invalid data model:: +[source,json] +---- +{ + "status": "VALIDATION_FAILED", + "summary": null, + "validation_failures": [ + { + "line_number": 2, + "reason": "UNRESOLVED_SOURCE", + "field_name": "datamodel_sources[0].guid", + "message": "unknown datamodel guid: 62f3e9b5-4fcc-4352-b8ad-fdddc228750" + } + ], + "diagnostics": [ + { + "sub_status": "FAILURE", + "messages": [ + "unknown datamodel guid: 62f3e9b5-4fcc-4352-b8ad-fdddc228750" + ] + } + ], + "operation_id": null +} +---- + +Inaccessible data models:: +[source,json] +---- +{ + "status": "VALIDATION_FAILED", + "summary": null, + "validation_failures": [ + { + "line_number": 2, + "reason": "ACCESS_DENIED", + "field_name": "datamodel_sources[0]", + "message": "Insufficient permissions on datamodel '62f3e9b5-4fcc-4352-b8ad-fdddc2287506'" + }, + { + "line_number": 8, + "reason": "ACCESS_DENIED", + "field_name": "datamodel_sources[0]", + "message": "Insufficient permissions on datamodel '62f3e9b5-4fcc-4352-b8ad-fdddc2287506'" + } + ], + "diagnostics": [ + { + "sub_status": "FAILURE", + "messages": [ + "Memory import validation failed with 2 error(s): Insufficient permissions on datamodel '44444444-4444-4444-4444-444444444444'; Insufficient permissions on datamodel '33333333-3333-3333-3333-333333333333'" + ] + } + ], + "operation_id": null +} +---- + +Character-limit validations:: +[source,json] +---- +{ + "status": "VALIDATION_FAILED", + "summary": [], + "validation_failures": [ + { + "line_number": 3, + "reason": "CHAR_LIMIT", + "field_name": "content.rule_definition", + "message": "content.rule_definition is 1073 characters; max allowed is 1000" + }, + { + "line_number": 49, + "reason": "CHAR_LIMIT", + "field_name": "content.user_query", + "message": "content.user_query is 1150 characters; max allowed is 1000" + }, + { + "line_number": 49, + "reason": "CHAR_LIMIT", + "field_name": "content.recipe", + "message": "content.recipe is 3574 characters; max allowed is 2000" + } + ], + "diagnostics": [ + { + "sub_status": "FAILURE", + "messages": [ + "Validation failures present; fix them and re-run to see the DRY_RUN preview." + ] + } + ], + "operation_id": "f0c0b5f3-6b48-4f20-9ebf-67e1b6bcd4e5" +} +---- + +Import success response:: + +[source,JSON] +---- +{ + "status": "SUCCESS", + "summary": [ + { + "memory_type": "RULES", + "source": { + "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506", + "type": "DATA_MODEL" + }, + "existing_record_count": 3, + "deleted_record_count": 3, + "inserted_record_count": 2, + "failed_record_count": 0 + }, + { + "memory_type": "RECIPES", + "source": { + "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506", + "type": "DATA_MODEL" + }, + "existing_record_count": 7, + "deleted_record_count": 7, + "inserted_record_count": 4, + "failed_record_count": 0 + }, + { + "memory_type": "ALWAYS_APPLY_RULES", + "source": { + "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506", + "type": "DATA_MODEL" + }, + "existing_record_count": 0, + "deleted_record_count": 0, + "inserted_record_count": 1, + "failed_record_count": 0 + } + ], + "validation_failures": [], + "diagnostics": [], + "operation_id": "10f7b113-7872-403b-a3ab-0152dc591b54" +} +---- + +== Additional resources + +* link:https://docs.thoughtspot.com/cloud/latest/spotter-memory[Spotter memory documentation, window=_blank] +* +++ REST API Playground - Export memory endpoint +++ +* +++REST API Playground - Import memory endpoint+++ diff --git a/modules/ROOT/pages/timezone.adoc b/modules/ROOT/pages/timezone.adoc index 59b43476a..26aa96fff 100644 --- a/modules/ROOT/pages/timezone.adoc +++ b/modules/ROOT/pages/timezone.adoc @@ -242,8 +242,7 @@ If the `ts_user_timezone` variable is configured for the Org or user, you can re The following example shows the formula syntax with the `ts_user_timezone` variable: -`sql_date_time_op ("CONVERT_TIMEZONE ('UTC', {0}, {1}"), ts_var (ts_user_timezone), [])` - +`sql_date_time_op ("CONVERT_TIMEZONE ('UTC', {0}, {1})", ts_var(ts_user_timezone), [])` Where: @@ -265,9 +264,7 @@ On query execution, the formula translates to: === Using hardcoded timezone values in formulas In ThoughtSpot Cloud 26.5.0.cl and earlier release versions, the timezone value was hardcoded in formulas to convert source values to the user's timezone. For example: ----- -sql_date_time_op ("CONVERT_TIMEZONE ('UTC', {0}, {1}"), '', []) ----- +`sql_date_time_op ("CONVERT_TIMEZONE ('UTC', {0}, {1})", '', [])` Where: diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 9ffba0d70..8619546fb 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -5,6 +5,7 @@ :page-title: TML :page-pageid: tml :page-description: The TML API endpoints allow you to export and import TML files +// SOURCE: SCAL-307283, SCAL-317357 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. @@ -17,6 +18,7 @@ The TML syntax varies per object type. However, all TMLs follow a general patter See the following pages for the detailed syntax of TML files for each object type: + * link:https://docs.thoughtspot.com/cloud/latest/tml-answers[TML for Answers, window=_blank] + +* link:https://docs.thoughtspot.com/cloud/latest/tml-collections[TML for Collections, window=_blank] + * link:https://docs.thoughtspot.com/cloud/latest/tml-connections[TML for Connections, window=_blank] + * link:https://docs.thoughtspot.com/cloud/latest/tml-joins[TML for Joins, window=_blank] + * link:https://docs.thoughtspot.com/cloud/latest/tml-liveboards[TML for Liveboards, window=_blank] + @@ -76,6 +78,63 @@ If you import only a Model object, it may take some time for the Model to become However, if you import a Model along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use. ==== +[#personalized-views-portability] +=== Personalized Views portability [earlyAccess eaBackground]#Early Access# + +Personalized Views support improved portability across ThoughtSpot environments. When importing a Personalized View TML set the `enable_personalized_view_upsert` to `true` in the API request to `POST /api/rest/2.0/metadata/tml/import`. ThoughtSpot then 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. + +To enable this feature for your instance, contact your ThoughtSpot administrator. + +Two new fields are added to the TML, make it easier to migrate Personalized Views between environments without creating duplicates. + +`author`::: +A new `author` field is added to the Personalized View TML during export. This field is used to delegate ownership to another user during import. + +`obj_id`::: +A new `obj_id` field provides stable cross-environment object identity for inter-Org deployments. Use the same `obj_id` value across environments to ensure consistent identity during migrations. + + + +==== Example for a Personalized View TML with Object ID + +[source,yaml] +---- + views: + - view_guid: ff83055b-a867-43e7-978e-106e907e1912 + obj_id: California-LT-ff83855b + name: California - LT + view_filters: + - column: + - Retail Sales - Classic::Store State + oper: in + values: + - California + is_public: false + author: + username: user1 + user_email: user1@thoughtspot.com +---- + +==== Limitation without this feature enabled + +ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/personalized-liveboard-views[personalized Liveboard views] let users apply filters and save configurations as named views on a Liveboard. +In multi-environment deployments (for example, a Dev instance and a Prod instance), these user-saved views can be lost when a Liveboard is updated and re-imported using the xref:tml.adoc[TML import API] or the UI *Import TML* option. +If the import is performed by an administrator account, all personalized views saved by end users are removed as part of this replacement. + +Why this happens?:: + +Personalized views are stored as user-owned objects linked to the Liveboard's GUID. +When an admin imports a Liveboard TML that matches an existing GUID, the import operation overwrites the Liveboard, and the associated user views are not carried forward. + +Workarounds:: +. Import as a non-admin user - ++ +The simplest workaround is to perform the final TML import in the production environment using a *non-admin user account* that has edit access to the Liveboard, rather than an admin account. +Because non-admin users do not have the authority to overwrite user-linked metadata during import, ThoughtSpot preserves the existing personalized views attached to the Liveboard. +. Embed existing saved views in the TML before import - ++ +You can export the current saved views from the production Liveboard, append them to the updated TML, and then import the combined TML. + == Import TML objects asynchronously The REST v1 and v2 `metadata/tml/import` APIs import TML objects synchronously. When you try to import large and complex metadata objects, the synchronous import operation takes more time to process data and sometimes can result in a timeout error. @@ -323,6 +382,7 @@ If Orgs are enabled on your instance, the API returns task status only for objec |**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. 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 +|=== diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index dc99edbb4..c253d2e69 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -23,6 +23,116 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Affects:* Developers, Administrators, End Users // ============================================================ +== August 2026 + +**Release version**: ThoughtSpot Cloud 26.8.0.cl + +*Upgrade notes*: ⚠️ Includes breaking changes and deprecations. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + +*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.8.0.cl* + +a| +[discrete] +==== Spotter embedding + +Spotter Analysts:: +[earlyAccess eaBackground]#Early Access# +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. For more information, see xref:embed-spotter.adoc#spotter-analysts[Spotter Analysts in embedded applications]. + +Spotter onboarding starter prompts:: +Embedded Spotter interface supports onboarding starter prompts to guide first-time users. When enabled, Spotter presents suggested questions based on the connected data model. For more information, see xref:embed-spotter.adoc#_enable_starter_prompts[Enable starter prompts in Spotter]. + +--- + +[discrete] +==== SpotterViz Insight Tiles [earlyAccess eaBackground]#Early Access# +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 embedding +The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: + +* *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. +* *Continuous Liveboard PDF export*: The exported PDF matches the exact Liveboard layout as displayed on screen. For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard downloads] and xref:data-report-v2-api.adoc#_file_formats[PDF downloads]. +* *PNG Liveboard export options*: The `image_resolution`, `image_scale`, and `include_header` options for PNG downloads. + +--- + +[discrete] +==== Navigation and homepage V1/V2 deprecated [.version-badge.deprecated]#Deprecated# +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. For more information, see xref:full-app-customize.adoc#nav-v1-v2-deprecation[V1 and V2 deprecation]. + +--- + +[discrete] +==== Wide logo dimension [.version-badge.breaking]#Breaking# +Starting from ThoughtSpot Cloud 26.8.0.cl, the recommended dimensions for the wide logo displayed on the ThoughtSpot login page have changed from 330x100px to *250x50px (5:1 aspect ratio)*. Logos uploaded at the previous dimensions may appear distorted or incorrectly scaled on the login screen. If you previously uploaded a wide logo at 330x100px, re-upload it at 250x50px to ensure correct display. + +For more information, see xref:customize-style.adoc#wide-logo[Customize the login page logo]. + +--- + + + +[discrete] +==== Granular download privileges +The new granular download privileges that replace the single general download privilege for RBAC enabled clusters are now generally available. + +* *Can Download Visuals* — Allows downloading chart images and visual exports. +* *Can Download Detailed Data* — Allows downloading raw tabular data (CSV, XLSX). + +These privileges can be assigned independently per user or group. Update privilege assignments in your embedded application accordingly. + +--- + +[discrete] +==== Personalized Views portability [earlyAccess eaBackground]#Early Access# +ThoughtSpot improves the portability of Personalized Views across environments. +Import operations use smart merge logic to avoid duplicating Personalized Views. + +Two new fields have been added to the TML for Personalized Views: + +* A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. +* Personalized Views now support `obj_id` for stable cross-environment object identity. + +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. + +--- + +[discrete] +==== Discoverability checkbox deprecation [.version-badge.breaking]#Breaking# +The *Make this Liveboard Discoverable* checkbox has been removed from the ThoughtSpot UI. Embedding applications that relied on discoverability for content visibility should review their sharing logic and update user-facing guidance for content access. For more information, see xref:deprecated-features.adoc#liveboardAnswerDiscoverable[Deprecation announcements]. + +--- + +[discrete] +==== Business terms autogeneration [.version-badge.deprecated]#Deprecated# +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] +==== Visual Embed SDK +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 in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|=== + == July 2026 **Release version**: ThoughtSpot Cloud 26.7.0.cl + @@ -30,7 +140,7 @@ This page lists new features, enhancements, and deprecated functionality introdu *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* @@ -94,7 +204,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]. --- @@ -110,7 +220,7 @@ For information about REST API v2 enhancements in this release, see the xref:res --- -|===== +|=== == June 2026 @@ -119,7 +229,7 @@ For information about REST API v2 enhancements in this release, see the xref:res *Recommended SDK versions*: Visual Embed SDK v1.49.0 and later [.cl-table, cols="2,4", frame=none, grid=none] -|===== +|=== a| [.cl-label] *Version 26.6.0.cl* @@ -166,7 +276,7 @@ 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]. +To improve load performance and reduce reload times, you can now enable the Liveboard cache option with a **Refresh** button that lets your users clear the cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Liveboard browser cache refresh]. --- @@ -180,7 +290,7 @@ The Visual Embed SDK version 1.49.0 includes several new features and enhancemen ==== 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 @@ -191,7 +301,7 @@ This release introduces new API endpoints for Spotter, connections and trusted a [.cl-table, cols="2,4", frame=none, grid=none] -|===== +|=== a| [.cl-label] *Version 26.5.0.cl* @@ -262,7 +372,7 @@ The Visual Embed SDK version 1.48.0 includes several new features and enhancemen ==== 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 @@ -283,7 +393,7 @@ 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. +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]. @@ -650,4 +760,4 @@ For information about the new features and enhancements introduced in Visual Emb ==== REST API For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -|=== \ No newline at end of file +|=== diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc index 3f551f338..5e08236a5 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc @@ -5,6 +5,10 @@ :page-pageid: rest-api__lesson-02 :description: A lesson on a simple implementation of the V2.0 using Python +[IMPORTANT] +==== +The workflows and examples in this tutorial use a legacy version of the ThoughtSpot REST API link:https://github.com/thoughtspot/thoughtspot_rest_api_python[ThoughtSpot Community SDK, window=_blank]. We recommend using the xref:python-sdk.adoc[ThoughtSpot-provided Python SDK for REST API v2], which supports both asynchronous and synchronous invocation, transparent token refresh, server-sent event (SSE) streaming, file uploads and downloads, and error handling. +==== == Get started We'll use the files from the link:https://github.com/thoughtspot/tse-api-tutorial[tse-api-tutorial GitHub repository, window=_blank] that you downloaded at the beginning of the tutorial. @@ -65,9 +69,8 @@ import requests import json thoughtspot_url = 'https://{}.thoughtspot.cloud' -org_id = 1613534286 +org_id = 0 api_version = '2.0' - ---- Now, let's construct the starting portion of any API endpoint URL and define the most basic headers that will be used by every call: @@ -77,12 +80,12 @@ Now, let's construct the starting portion of any API endpoint URL and define the ... base_url = '{thoughtspot_url}/api/rest/{version}/'.format(thoughtspot_url=thoughtspot_url, version=api_version) api_headers = { - 'X-Requested-By': 'ThoughtSpot', + 'X-Requested-By': 'ThoughtSpot', 'Accept': 'application/json' } ---- -== 02 - Use a Session object +== 02 - Use a session object Rather than setting the full configuration for each HTTP request, you can construct a `Session` object from the `requests` library, which keeps an open HTTP connection and maintains settings like headers and cookies between individual HTTP actions. @@ -99,7 +102,7 @@ requests_session = requests.Session() requests_session.headers.update(api_headers) # Define the JSON message, in Python object syntax (close but not exactly JSON) -json_post_data = { // a request body } +json_post_data = { # a request body } # Set the URL of the endpoint url = base_url + "{api_endpoint_ending}" @@ -123,7 +126,7 @@ In the REST API V2.0 Playground: . Go to *Authentication* > *Get Full Access Token*. . Specify the parameters. -. Copy the JSON body from the right side of the Playground. Python dicts use the same syntax, but you must update booleans to be *uppercase*. +. Copy the JSON body from the right side of the Playground. Python dicts use the same syntax, but you must capitalize Python's boolean keywords (`True`/`False`). . Replace any hard-coded values with the *global variables* you declared so that you can easily update requests at the top of your script and ensure those values change everywhere they are used: + [,python] @@ -137,13 +140,13 @@ json_post_data = { "password": "y0urP@ssword", "validity_time_in_sec": 3600, "org_id": org_id, - "auto_create": False # make sure to uppercase in Python + "auto_create": False # capitalize booleans in Python } ---- . Make a `.post()` request using the `Session` object. + + -We expect a JSON response on success, which you can access using the `.json()` method of the `Response` object. +We expect a JSON response on success, which you can access using the `.json()` method of the `Response` object. + From the Playground, we can see that there is a `token` property in the response. @@ -152,14 +155,13 @@ From the Playground, we can see that there is a `token` property in the response + [,python] ---- -.... +... resp = requests_session.post(url=url, json=json_post_data) resp_json = resp.json() print(json.dumps(resp_json, indent=2)) token = resp_json["token"] print("Here's the token:") print(token) -.... ---- ==== Run the script to test @@ -199,7 +201,7 @@ Unfortunately, making a REST API request to a web server can result in any numbe Good coding involves testing for and handling error situations. === Using try and except in Python -Python code raises `link:https://docs.python.org/3/tutorial/errors.html[Exceptions, target=_blank]` when an error is encountered. +Python code raises `link:https://docs.python.org/3/tutorial/errors.html[Exceptions, window=_blank]` when an error is encountered. If an `Exception` is raised and is not *handled*, the script exits and displays the message provided with the Exception and other details of what failed. @@ -210,28 +212,28 @@ Every HTTP request can potentially result in an error, and we don't want to cont The most generic `try...except` block will capture *any* `Exception`: [,python] ---- -try: +try: resp = requests_session.post(url=url, json=json_post_data) resp_json = resp.json() # Returns JSON body of resp to Python Dict print(resp_json) token = resp_json["token"] -except Exception as e: - # do whatever is necessary in exception case +except Exception as e: + # do whatever is necessary in exception case # Code after the try block will now run even after Exception ---- === Checking for requests HTTPError exceptions -The `requests` library does not raise an `Exception` when an HTTP request completes "properly", that is to say a well-formed HTTP response is received from a request. +The `requests` library does not raise an `Exception` when an HTTP request completes "properly," that is to say a well-formed HTTP response is received from a request. However, as you saw in the previous lesson, HTTP responses include a *Status Code* that indicates if the requested action was a *Success* or an *Error*. -To raise `Exceptions` when the response does not include a *Success* status code, call the `Response.raise_for_status()` method for each call, which throws the specific `requests.exceptions.HTTPError` `Exception` when a 400 series or 500 status code is returned: +To raise `Exceptions` when the response does not include a *Success* status code, call the `Response.raise_for_status()` method for each call, which throws the specific `requests.exceptions.HTTPError` `Exception` when a 400 or 500 series status code is returned: [source,python] ---- -try: +try: resp = requests_session.post(url=url, json=json_post_data) resp.raise_for_status() print(resp) @@ -265,7 +267,7 @@ json_post_data = { "password": "y0urP@ssword", "validity_time_in_sec": 3600, "org_id": org_id, - "auto_create": False # make sure to uppercase in Python + "auto_create": False # capitalize booleans in Python } try: @@ -309,7 +311,7 @@ try: ... ---- -You may have noticed many steps that are repeated each time for any given request. +You may have noticed many steps that are repeated each time for any given request. In the next lesson, we'll cover using a *library* that wraps most of these repeated steps, so that you can focus simply on the logic of your API workflows. diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index ff8f6c417..d2f300ec7 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -22,8 +22,8 @@ module.exports = { // 'https://developers.thoughtspot.com/docs/26.3.0.cl?pageid=whats-new' // - GA: ' /docs/whats-new' //linkHref: '/docs/whats-new', - linkHref: '/docs/26.7.0.cl?pageid=whats-new', - linkText: 'Version 26.7.0.cl', + linkHref: '/docs/26.8.0.cl?pageid=whats-new', + linkText: 'Version 26.8.0.cl', openInNewTab: true, }, TYPE_DOC_PREFIX: 'typedoc', @@ -48,10 +48,10 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '26.7.0.cl', - link: '26.7.0.cl', + label: '26.8.0.cl', + link: '26.8.0.cl', subLabel: 'Cloud (Latest)', - iframeUrl: 'https://developer-docs-26-7-0-cl.vercel.app/docs/', + iframeUrl: 'https://developer-docs-26-8-0-cl.vercel.app/docs/', }, ], CUSTOM_PAGE_ID: { diff --git a/static/doc-images/images/style-applogo.png b/static/doc-images/images/style-applogo.png index cad220b36..f88923e23 100644 Binary files a/static/doc-images/images/style-applogo.png and b/static/doc-images/images/style-applogo.png differ diff --git a/static/doc-images/images/style-widelogo.png b/static/doc-images/images/style-widelogo.png index 69bee0157..dfa82108f 100644 Binary files a/static/doc-images/images/style-widelogo.png and b/static/doc-images/images/style-widelogo.png differ